Intercept intialization requests to STDIO servers

[eleftherias]

Current Limitation

If multiple clients send an initialize request, ToolHive forwards the request to the STDIO workload, which may reject the request or behave unexpectedly, since the expected behaviour is not described by the protocol.

Proposed Solution

ToolHive can a single initialization request to the MCP server container, and intercept any initialization requests coming from the client, responding with a cached response.

Flow:

• When an MCP server is started, ToolHive sends an initialization request and caches the response
• When ToolHive receives an initialization request from a client:
  • It should not forward the request to the MCP server
  • It should respond with the cached response
  • It should respond with the session ID (this is already implemented)

[therealnb]

Every time a server is disabled and re-enabled in vscode/cursor config initialise is called, so any MCP server that can't handle multiple inits is in trouble anyway, regardless of the spec. See #2499.

On a different note, if we are muiltplexing the initialize function, how are we coping with clients with different capabilities and versions?

[amirejaz]

Opened #6153 for this. The implementation differs from the proposal above, so flagging it here rather than letting reviewers discover the mismatch.

What changed vs the proposal. This issue suggests ToolHive send its own initialize when the server starts and cache that response. #6153 instead caches the first client's handshake: the first initialize to arrive is forwarded and its result stored, and every later one is answered from the cache without reaching the backend.

The reasons for the switch:

• A proxy-owned handshake at startup means the proxy has to invent a protocol version and a client capability set. Caching the first real client's handshake lets an actual client negotiate, and whatever it agreed is what later clients receive.
• It needs no changes to startup ordering or readiness, which is its own can of worms (see handle impetulant client config changes #2499).
• It is a much smaller change, and it reproduces exactly what go-sdk v1.6.1 and earlier did when a repeated initialize returned the original result. We are not inventing a compromise, we are moving that behaviour into the component that owns the multiplexing.

@therealnb's question from November — "if we are multiplexing the initialize function, how are we coping with clients with different capabilities and versions?" — is the thing that needed answering before any of this could land. Three separate directions, and only one of them actually matters:

• Server capabilities (tools, resources, prompts, logging) live in the InitializeResult and do not vary by client. Replaying them to everyone is simply correct, not a compromise.
• Client capabilities (roots, sampling, elicitation) travel in the initialize request, so only the first client's ever reach the backend. This turns out to be inert: any server→client request those capabilities would enable is already rejected outright by this proxy (dispatcher.go:179), because with N clients on one backend session it cannot attribute such a request to a session. So the backend believing it has sampling available changes nothing observable.
• The negotiated protocol version is the one genuinely shared, client-visible value. A client asking for a different version gets the first client's back, and per the lifecycle spec should disconnect if it cannot speak it. This is inherent to collapsing N client sessions onto one backend session, and it is what go-sdk did too when it replayed a cached result.

Two things worth knowing that are not in the description above.

The blast radius is wider than the health check in #5890. Every vMCP call verb builds a fresh client and handshakes, so once the aggregator claims the single handshake at startup, tool calls fail too. A ping-based health check would have made the backend report healthy while remaining unusable.

go-sdk also rejects a repeated notifications/initialized, not just a repeated initialize (mcp/server.go:1424 alongside :1978), so #6153 gates that notification the same way.

Verified end to end against ghcr.io/github/github-mcp-server:v1.6.0 over stdio: on main the second and third client handshakes fail with duplicate "initialize" received; with the change all three succeed, and a cache-served client can complete notifications/initialized and tools/list normally.

One limitation called out in the PR: the cache is not invalidated when a container is replaced underneath a running proxy. The re-attach path only fires while the container is still running (same live process, session still valid), so clearing the cache there would break the common case. Distinguishing a genuinely new process needs a signal the proxy does not currently have.