MCP endpoints

Each Virtual MCP is exposed as a single Streamable HTTP MCP endpoint. An AI client connects to that one endpoint and sees the combined tool surface of every connector in the Virtual MCP.

POST https://bridgemcp.net/api/v1/mcp/{virtual-mcp-id}

The URL does not contain a protocol version and existing client configuration does not need to change. BridgeMCP supports the five MCP revisions from 2024-11-05 through 2026-07-28; the client selects a compatible revision automatically.

Modern and legacy clients

Modern 2026-07-28 clients send independent, self-describing POST requests. Each request carries the protocol version and client capabilities in params._meta, plus matching HTTP routing headers:

  • MCP-Protocol-Version and Mcp-Method on every request.
  • Mcp-Name on named calls such as tools/call.

BridgeMCP validates the headers against the JSON-RPC body. MCP client libraries normally add these fields, so users should configure only the endpoint URL and authentication rather than writing the headers by hand.

Older clients continue to start with initialize and notifications/initialized. BridgeMCP accepts that compatibility flow on the same POST URL without creating a protocol session or returning Mcp-Session-Id. Modern server/discover advertises 2026-07-28; legacy revisions are selected through their initialize negotiation.

Request flow

When an AI client connects, the gateway performs four steps:

  1. Authenticate the request using the API key or OAuth token in the Authorization header.
  2. Resolve which connectors belong to the requested Virtual MCP.
  3. List tools (tools/list): aggregate the tool lists from every upstream connector.
  4. Call tools (tools/call): route each call to the correct connector, execute it, record the call, and return the result.

Freshness and tool-list changes

Modern server/discover and tools/list results include cache hints. Discovery is private and immediately stale so a client can re-check capabilities after a deployment. Aggregated tool lists are private to the authorization context and use a conservative freshness period derived from their upstream connectors. A partial list has ttlMs: 0. A tool-list change notification invalidates an otherwise fresh client cache.

Authenticated Virtual MCP endpoints support subscriptions/listen for toolsListChanged. The first stream message acknowledges the supported event, then later changes tell the client to call tools/list again. These notifications are bounded, best-effort invalidation hints rather than a lossless event log: bursts can coalesce into one pending hint or be dropped while the listener is busy. After an invalidation, call tools/list again before using the changed definitions. Clients must still honor cache TTLs and explicitly re-list whenever freshness matters. If the stream drops, reconnect with a new listen request and refresh tools/list; BridgeMCP does not replay missed notifications and does not expose prompt or resource subscriptions.

Tool calls that need more input

A modern upstream tool may return resultType: "input_required" and ask a compatible client for elicitation, sampling, or roots input. BridgeMCP passes that Multi Round-Trip Request (MRTR) through without storing its opaque request state. The retry is a new request and must repeat the state and responses.

Capabilities are declared per request. If the client did not declare every capability the upstream request needs, BridgeMCP returns -32021 (MissingRequiredClientCapability) instead of treating the interim result as a completed tool call. Legacy clients therefore receive an actionable error when a modern upstream unexpectedly requires input they cannot supply.

Tool namespacing

Different connectors can expose tools with the same name. To keep tool provenance unambiguous and avoid collisions, the gateway namespaces every aggregated tool as:

{connector_name}.{original_tool_name}

For example, a GitHub connector’s pull_request_read tool is presented as github.pull_request_read. On a tools/call, the gateway splits the name on the first . to determine which connector to route to, then calls the upstream server with the original, un-prefixed tool name.

The upstream tool’s input schema is preserved as-is, so clients get accurate parameter validation and autocomplete.

Tool overrides

Each connector can customize its exposed tools with per-tool overrides: enable or disable individual tools, or replace a tool’s description. This lets you trim a noisy upstream server down to the tools your agents actually need.

{
  "read_file":  { "enabled": true, "description": "Read a file from the project" },
  "write_file": { "enabled": false }
}

What is proxied

The gateway aggregates and proxies tools. Resource and prompt proxying are not part of the current tool-aggregation surface.

Next steps