# How the Agent Context Transport Probe Enables Capability Discovery in OpenWork

> Discover how the agent context transport probe in OpenWork verifies endpoint reachability and protocol compatibility for seamless capability discovery. Learn more.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: internals
- Published: 2026-08-09

---

**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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
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:

```bash
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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/apps/server/src/agent-context-transport-probe.ts) with comprehensive test coverage in the corresponding [`.test.ts`](https://github.com/different-ai/openwork/blob/main/.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:

```bash
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.