How the Agent Context Transport Probe Enables Capability Discovery in OpenWork

The agent context transport probe is a low-level diagnostic mechanism that verifies Cloud MCP endpoint reachability, TLS trustworthiness, and protocol compatibility before the system attempts higher-level capability discovery.

The agent context transport probe serves as the foundational security checkpoint in the OpenWork system, validating that configured Cloud MCP endpoints can safely handle the Machine-Control-Protocol (MCP) handshake required for tool discovery. Located in the different-ai/openwork repository, this probe isolates network-layer failures from protocol-level errors by performing endpoint sanitization, certificate verification, and TLS version negotiation. Its evidence-based approach ensures that only reachable and trustworthy endpoints proceed to the catalog probe for capabilities like search_capabilities and execute_capability.

What the Agent Context Transport Probe Does

The probe executes a five-phase diagnostic sequence defined in apps/server/src/agent-context-transport-probe.ts. Each phase gathers specific evidence about the endpoint's transport-layer behavior.

Endpoint Sanitization and Validation

The safeTransportEndpoint function performs strict URL validation before any network connection occurs. It verifies that the supplied URL ends with the required /mcp/agent path, rejects URLs containing user info, query strings, or fragments, and mandates HTTPS for all non-loopback hosts. If the endpoint fails these checks, the probe returns early with performed: false and a descriptive skipReason.

Local Trust Gathering

Before initiating connections, the probe collects evidence about the local trust environment using extraCaEvidence and caCertificateCount. It records the systemCaCertificateCount and bundledCaCertificateCount from the Node.js CA store, and inspects the file referenced by NODE_EXTRA_CA_CERTS to report its readability and certificate count.

TLS Handshake and Certificate Extraction

The connectTls function attempts connections in two stages. First, it tries a standard TLS handshake with rejectUnauthorized: true. If this fails, a second attempt with rejectUnauthorized: false captures the presented certificate chain via servedChainFromCertificate. The probe uses isCertificateVerificationError to distinguish between certificate trust issues and other network failures, storing the results in verifiedHandshake and verifyErrorCode.

Protocol Version Fallback

When the initial handshake times out, the probe executes timeoutVersionEvidence to test TLS 1.3 and TLS 1.2 support with short timeouts. This determines whether the server supports modern protocol versions or requires legacy compatibility, recording results in tls13Handshake and tls12Handshake.

Result Composition

The probeCloudEndpointTransport function returns a CloudEndpointTransportProbe object containing:

• Endpoint metadata: endpointOrigin, endpointProtocol
• Execution status: performed, skipReason (if applicable)
• Handshake results: verifiedHandshake, verifyErrorCode
• Network evidence: dnsResolved, tcpConnected
• TLS specifics: tls13Handshake, tls12Handshake
• Certificate data: servedChain, servedChainLength

How the Transport Probe Feeds Capability Discovery

The transport probe acts as a gatekeeper for the catalog probe (probeOpenworkCloudCatalog in apps/server/src/agent-context-cloud-probe.ts), which performs the actual MCP handshake to retrieve available tools.

Pre-Handshake Verification

The catalog probe first checks endpoint eligibility (local workspace status, runtime config presence, and safeCatalogEndpoint validation). It then invokes the transport probe before any HTTP-level RPC calls, ensuring that network fundamentals are confirmed before attempting the initialize → tools/list sequence.

Network Reachability Confirmation

The catalog probe requires dnsResolved and tcpConnected to be true in the transport probe results. If either is false, indicating DNS resolution failure or TCP connection refusal, the catalog probe aborts immediately with a network-error code rather than attempting the MCP handshake.

TLS Trust Validation

When isCloudEndpointCertificateVerificationFailure returns true based on the transport probe's verifyErrorCode, the catalog probe surfaces a specific tls_error code. This distinction allows operators to differentiate between untrusted certificates and general network outages.

Diagnostic Evidence Attachment

The certificate chain extracted by the transport probe (servedChain) is attached to the final probe report. This allows operators to inspect exactly which certificates were presented by the endpoint, facilitating debugging of trust anchor mismatches or expired intermediate certificates.

Implementation Examples and Testing

You can invoke the transport probe directly for diagnostic purposes:

import { probeCloudEndpointTransport } from "./agent-context-transport-probe.js";

async function checkEndpoint(url: string) {
  const result = await probeCloudEndpointTransport({
    endpointUrl: url,
    performProbe: true,
  });

  console.log("Endpoint origin:", result.endpointOrigin);
  console.log("TLS handshake verified:", result.verifiedHandshake);
  console.log("Error code:", result.verifyErrorCode);
  console.log("Certificate chain length:", result.servedChainLength);
}

To execute the comprehensive test suite covering SNI handling, self-signed certificate detection, and network failure scenarios:

bun test apps/server/src/agent-context-transport-probe.test.ts

Key test cases verify that raw IP addresses omit the servername field while DNS names include it, that self-signed certificates trigger verification errors while still returning the chain, and that NODE_EXTRA_CA_CERTS files are correctly parsed for trust evidence.

Key Source Files

• apps/server/src/agent-context-transport-probe.ts – Core implementation containing probeCloudEndpointTransport, safeTransportEndpoint, and TLS connection logic.
• apps/server/src/agent-context-transport-probe.test.ts – Test suite validating SNI behavior, certificate extraction, DNS failures, and local trust evidence.
• apps/server/src/agent-context-cloud-probe.ts – Higher-level catalog probe that consumes transport probe results before performing MCP capability discovery.
• evals/packages/behaviors/src/diagnostics.ts – Example of dynamic transport probe imports for runtime diagnostic collections.
• packages/enterprise-mcp-mock-server/src/testing/probe.ts – Mock implementation used for testing enterprise MCP server interactions.

Summary

• The agent context transport probe validates Cloud MCP endpoints before capability discovery begins, isolating network and TLS issues from protocol errors.
• It performs strict endpoint sanitization, local trust evidence collection, and dual-phase TLS handshake attempts to extract certificate data even from failed connections.
• The probe returns structured evidence including DNS resolution status, TCP connectivity, TLS version support, and complete certificate chains.
• The catalog probe consumes this evidence to abort early on network failures, surface specific TLS errors, and attach diagnostic certificate data to operator reports.
• Implementation resides primarily in apps/server/src/agent-context-transport-probe.ts with comprehensive test coverage in the corresponding .test.ts file.

Frequently Asked Questions

What is the difference between the transport probe and the catalog probe?

The transport probe (probeCloudEndpointTransport) operates at the network layer to verify endpoint reachability and TLS trustworthiness. The catalog probe (probeOpenworkCloudCatalog) operates at the application layer to perform the MCP handshake and retrieve the list of available tools (capabilities). The transport probe must succeed before the catalog probe attempts its work.

How does the probe handle self-signed certificates?

When a TLS handshake fails due to certificate verification, the probe makes a second connection attempt with rejectUnauthorized: false to extract the presented certificate chain via servedChainFromCertificate. It records the verification failure in verifyErrorCode while still returning the certificate data, allowing operators to inspect the untrusted chain.

Why does the transport probe require HTTPS for non-loopback endpoints?

The safeTransportEndpoint function enforces HTTPS for all hosts except loopback addresses to prevent credential or data exposure over unencrypted channels. This security constraint ensures that Cloud MCP endpoints, which may transmit sensitive capability metadata, are protected in transit.

How can I run the transport probe tests locally?

Execute the Bun test runner against the probe's test file:

bun test apps/server/src/agent-context-transport-probe.test.ts

This command runs validations for SNI handling, self-signed certificate detection, connection refusal scenarios, DNS resolution failures, and local CA certificate parsing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}