Remove the vMCP Modern stateless dispatch kill-switch before GA

[jhrozek]

Part of #5743. Follow-up to #5953.

Context

#5953 serves MCP 2026-07-28 ("Modern") stateless requests through vMCP behind a default-off startup kill-switch (TOOLHIVE_VMCP_MODERN_STATELESS). When off, well-formed Modern requests fall through to the SDK path (safe version-downgrade) instead of the hand-rolled Modern dispatcher.

The switch exists as a temporary safety lever, not a permanent feature gate. The Modern wire envelope is hand-rolled to mirror go-sdk v1.7.0-pre.3, a version ToolHive does not import (the module is on v1.6.1 via mcpcompat). So:

• there is no compile-time check that the envelope shapes match the real SDK, and
• the envelope tests assert against hand-written expected JSON, not real SDK bytes.

Until that's independently validated, a config-only lever to fall back to the SDK path (rather than revert-and-redeploy) is cheap insurance. See the discussion on #5953.

What to do

Remove the kill-switch and serve well-formed Modern requests unconditionally:

• Config.ModernDispatchEnabled and its plumbing (server.Config / ServerConfig, derive.go, serve.go, pkg/vmcp/cli/serve.go env read).
• The if !s.config.ModernDispatchEnabled branch in classifyingHandler (pkg/vmcp/server/classification.go).
• The TOOLHIVE_VMCP_MODERN_STATELESS env var and its docs.
• The kill-switch-off tests / the newRealModernTestServer vs newRealTestServer split introduced to keep the switch on for Modern tests.

(Classification precision already guarantees zero Legacy impact — non-Modern requests never reach the dispatcher regardless — so removal only affects whether Modern is served, not Legacy.)

Blocked on / done when

Do this once Modern serving is validated against the real wire contract, i.e. either:

• the Live e2e tests for dual-era stateless proxy behavior (local, k8s, CI) #5837 dual-era conformance harness lands and passes for Modern (independent go-sdk v1.7 client / upstream conformance), or
• mcpcompat adopts go-sdk v1.7 (Adopt go-sdk v1.7 for MCP 2026-07-28 stateless support #5754) so the Modern shapes are compile-checked and the hand-rolled envelope can be swapped for real SDK types.

Must not ship to production/GA with the kill-switch still present.

[JAORMX]

There is an unstated third gate: subscriptions/listen

The two "done when" gates in the description are now both met — #5837's dual-era conformance harness landed, and go-sdk v1.7 was adopted via #5993 — and the sequencing @jhrozek asked for on #6009 is satisfied, since that is merged. So this looked ready. It is not, and the reason is worth recording before anyone else picks it up.

Removing the server/discover exemption breaks every client that wants server→client traffic.

The exemption was added in #6009 to keep version negotiation possible while the switch was off. It turns out to have been doing load-bearing work well beyond conformance: it is what steered Modern-first clients onto Legacy.

Traced against a real go-sdk client:

1. go-sdk v1.7's Connect is Modern-first: it POSTs server/discover with MCP-Protocol-Version: 2026-07-28.
2. Switch off (today): the exemption passes that through to the SDK's stateful server, which answers with Legacy-only supportedVersions, so the client negotiates Legacy and everything works.
3. Modern unconditional: dispatchModernDiscover answers supportedVersions: ["2026-07-28", "2025-11-25"] (modern_envelope.go:282), so the client negotiates Modern.
4. mcpcompat's Initialize installs the list-changed handlers unconditionally, and go-sdk opens the standalone stream whenever any handler is set — so the client POSTs subscriptions/listen.
5. dispatchModern's method switch has no subscriptions/listen case (modern_dispatch.go:81-99 covers tools/*, resources/*, prompts/*, completion/complete, ping, server/discover) → -32601 → go-sdk treats Connect as failed and tears the connection down.

REQ POST proto="2026-07-28" method=server/discover
  RESP 200 {...,"supportedVersions":["2026-07-28","2025-11-25"],...}
REQ POST proto="2026-07-28" method=subscriptions/listen
  RESP 404 {"error":{"code":-32601,"message":"method not found"},...}

Net effect: elicitation, sampling, progress, logging and list_changed clients can no longer connect to vMCP at all.

This is pre-existing, not a defect in the removal. Confirmed by control: setting ModernDispatchEnabled: true on clean main with the removal stashed reproduces identical failures. The kill-switch has been masking it. 20 top-level tests regress, all one root cause — 5 in pkg/vmcp/server (TestForwarding_{Elicitation,Sampling,Progress,Logging}_RealBackend and the sampling session-isolation case) and 15 in test/integration/vmcp.

pkg/vmcp/session/factory.go:246 already documents this exact hole for the backend edge — "its push channel is subscriptions/listen, which vMCP does not implement". Removing the switch exposes the same hole on the client edge.

Consequences for this issue

• The third gate is: implement subscriptions/listen in dispatchModern (or otherwise stop advertising Modern to clients that need a push channel). That is a Modern push-channel design task, not part of a kill-switch removal, and it plausibly wants its own issue under Epic: MCP protocol currency and 2026-07-28 stateless readiness #5743.
• Option "drop the -32022 but keep the exemption" does not work. vMCP would serve Modern verbs while denying Modern in its own capability probe, leaving Modern dispatch unreachable for any well-behaved client.
• The dual-era e2e suite would not have caught this, because e2e.RawMCPClient never sends the server/discover probe. Worth attention independently of this issue: the suite's Modern coverage does not exercise the negotiation path a real SDK client takes.

A draft PR carrying the full removal plus this analysis is being opened and deliberately left un-mergeable, so the work and the wire trace are reviewable rather than re-derived later.

Generated with Claude Code