LATEST_PROTOCOL_VERSION misdescribes what the shim requests, and Initialize silently discards the caller's version

[JAORMX]

Rescoped. This issue originally bundled two conformance findings that turned out to be upstream-only; those are now go-sdk#1112 and go-sdk#1113. See the correction comment for why neither was fixable here. What remains below is shim-side.

The defect

mcpcompat exports a constant that no longer describes what the shim does:

// mcpcompat/mcp/jsonrpc.go:15
const LATEST_PROTOCOL_VERSION = "2025-11-25"

Meanwhile go-sdk's latestProtocolVersion is 2026-07-28, and client.Initialize calls Connect(ctx, tr, nil) — so the shim always requests 2026-07-28 on the wire, whatever the caller asked for. request.Params.ProtocolVersion is read nowhere in Initialize.

The combination is what makes this worth fixing: a consumer reads LATEST_PROTOCOL_VERSION, reasonably concludes the shim speaks 2025-11-25, passes it to Initialize, and gets 2026-07-28 requested — silently.

That is not hypothetical. Every ToolHive production initialize does exactly this:

• pkg/transport/bridge.go:197
• pkg/vmcp/client/client.go:852
• pkg/vmcp/session/internal/backend/mcp_session.go:553

Important: do not "fix" this by honouring the request

The substitution is load-bearing for ToolHive today. Because the wire request is 2026-07-28, a Modern-capable backend answers initialize with 2026-07-28, which is precisely how ToolHive's legacyInit detects a mis-cached backend and flips its revision cache Legacy→Modern (stacklok/toolhive#5997, pinned by TestListCapabilities_MisCachedLegacy_SelfHealsViaSDKNegotiation).

Honouring a requested 2025-11-25 would make that backend negotiate 2025-11-25, the self-heal would never fire, and vMCP's Legacy→Modern correction would silently regress. Rejecting an unhonourable request would break all three production call sites immediately, since they all pass a version that cannot be honoured.

Honouring is also not currently possible: ClientSessionOptions.protocolVersion is unexported upstream (go-sdk#1113).

Proposed work — documentation and validation only, no behaviour change

• Document client.Initialize: state plainly that Params.ProtocolVersion does not influence the wire version, that go-sdk requests its own latest and negotiates down, and link go-sdk#1113. This removes the silence, which is the actual harm.
• Fix or document LATEST_PROTOCOL_VERSION. Two options, and this is the decision worth discussing:
  • Document it as an mcp-go compatibility constant that reflects neither the revision the shim requests nor the newest it supports. Zero risk.
  • Change it to 2026-07-28. Behaviourally a no-op for Initialize (the value is discarded anyway), but it is exported and consumers may compare against it, so it needs a consumer sweep first. toolhive uses it in at least the three production sites above plus several tests.
• Validate genuinely invalid input: a requested version that go-sdk does not recognise at all is unambiguously a caller bug and can return an error, with no effect on any current caller.

Non-goal

Making the shim honour arbitrary requested versions. That is blocked on go-sdk#1113 and, per the above, would need a coordinated change in toolhive because the current behaviour is depended upon.

Generated with Claude Code

[JAORMX]

Correction: neither item is fixable in this repo, and item 2's suggested fix would break ToolHive production

I went to implement both against mcpcompat and found the suggested fixes above are wrong. Recording that before anyone acts on them.

Item 1 has no shim-side seam

filterSupportedVersions (go-sdk mcp/server.go:915) consults only the Transport. SSEHandler.ServeHTTP constructs the SSEServerTransport internally and calls server.Connect(ctx, transport, nil) (mcp/sse.go:274), and SSEOptions exposes exactly one field, DisableLocalhostProtection. There is no hook, option, or exported constructor that lets mcpcompat supply or wrap the transport.

So "filter in the shim's SSE server construction" is not possible. The realistic options are:

1. Upstream, small: have go-sdk's SSEServerTransport implement ProtocolVersionSupporter, returning false for 2026-07-28. This is the correct fix and is a handful of lines.
2. Shim-side, disproportionate: stop using NewSSEHandler and reimplement it — session map, POST dispatch by sessionid, the endpoint event, DNS-rebinding protection — purely to wrap the transport. Not worth it for a conformance nit with no ToolHive impact (vMCP's Modern egress only ever POSTs to the configured BaseURL and never reaches /messages).

Item 2 is worse than described, and must NOT be "fixed" as suggested

Two facts I missed when filing:

ClientSessionOptions.protocolVersion is unexported, commented "for testing" (mcp/client.go:251). The shim therefore cannot honour a caller's requested version even if it wanted to. Option one of my suggested fix is unavailable.

The silent substitution is load-bearing for ToolHive. mcpcompat.LATEST_PROTOCOL_VERSION is "2025-11-25" (mcpcompat/mcp/jsonrpc.go:15), while go-sdk's latestProtocolVersion is "2026-07-28". Every ToolHive production initialize passes the former:

• pkg/transport/bridge.go:197
• pkg/vmcp/client/client.go:852
• pkg/vmcp/session/internal/backend/mcp_session.go:553

…and silently gets 2026-07-28 requested on the wire. That is precisely why legacyInit observes InitializeResult returning 2026-07-28 and flips its per-backend cache Legacy→Modern — the in-band self-heal added in stacklok/toolhive#5997, pinned by TestListCapabilities_MisCachedLegacy_SelfHealsViaSDKNegotiation.

If the shim started honouring the request, a Modern-capable backend would negotiate 2025-11-25, the self-heal would never fire, and vMCP's Legacy→Modern correction would silently regress. And rejecting an unhonourable request — my other suggestion — would fail all three production paths immediately, since they all pass a version that cannot be honoured.

So the earlier framing ("silently substituting is the worst of the three options") was wrong here: the substitution is currently the only thing that works, and consumers have unknowingly built on it.

What is actually actionable

In this repo, safely:

• Document the behaviour on client.Initialize: Params.ProtocolVersion does not influence the wire version; go-sdk requests its own latest and negotiates down. That removes the silence without changing behaviour.
• Flag LATEST_PROTOCOL_VERSION as the real defect — it is an exported constant named "latest" that is a revision behind what the shim actually requests, and callers reason from it incorrectly. Changing its value needs consumer review; documenting the discrepancy does not.
• Validate genuinely invalid input — a requested version go-sdk does not know at all is unambiguously a caller bug and can fail loudly with no effect on current callers.

Upstream (modelcontextprotocol/go-sdk), to make real fixes possible later:

• SSEServerTransport implementing ProtocolVersionSupporter (item 1).
• A public client protocol-version option, so a caller can request a specific revision deliberately (item 2).

Retitling/rescoping this issue accordingly is probably worthwhile; I have not done so unilaterally since it changes what the issue is asking for.

Generated with Claude Code