Serve the 2026-07-28 protocol over stdio: decide the era from the opening request

Merged
MA
4mo ago
+335-253

Supersedes #3151, which grew far beyond the actual fix. This one does one thing.

Why

The stdio driver derived a connection's protocol era from whichever request completed first, so it could never host a request that doesn't return. subscriptions/listen was therefore hard-refused over stdio with -32601, even though the same connection advertised tools.listChanged: true. The same rule meant a legacy initialize arriving while a slow 2026 request was in flight got accepted and locked the connection out from under that request.

What changed

serve_dual_era_loop now decides the era from the client's first request, once, before any handler runs, and replays that frame into the chosen serving loop:

  • a request carrying the 2026-07-28 per-request _meta envelope opens a 2026 connection;
  • anything else (the initialize handshake, which doesn't exist at 2026 versions even when a client stamps the envelope on it) opens a 2025 one;
  • a later claim from the other era is refused in one place: initialize on a 2026 connection gets -32022 naming the served versions, an enveloped request on a handshake connection gets -32600.

With the era no longer waiting on completions, the subscriptions/listen refusal is simply deleted; the handler was always transport-agnostic and now serves over the stream pair like any other 2026 request. No public API changes: same driver signature, Server, MCPServer, the dispatcher, and the transports are untouched.

Observable corners that move

  • Listen works over stdio (previously -32601).
  • initialize during an in-flight 2026 request: refused -32022; the running request finishes. (Previously accepted, re-locking the connection.)
  • A failed 2026 opening probe (unknown method, unsupported version, malformed envelope) still leaves the connection on 2026, so a follow-up initialize gets -32022 — which is the spec's own "this server is modern, use a listed version" signal — rather than running the handshake.
  • server/discover sent without the envelope is 2025-era vocabulary: it answers -32601 and a fallback handshake still lands on the same connection (previously -32602, same client outcome).

Not in scope

The trailing {"code": 0, "message": "Request cancelled"} frame the dispatcher writes after a client cancel is a separate stdio conformance item and stays as it is here.

Testing

The dual-era tests in tests/server/test_runner.py are updated to the new rule (two that encoded "the era locks on the first request to succeed" are gone; one now drives an actual subscriptions/listen over the stream pair through ack and graceful close; the straddle case is pinned). Full suite green with 100% branch coverage; pyright and ruff clean.

One process note: AGENTS.md asks that new 2026 features carry a matching conformance-suite test. I don't believe the upstream conformance suite covers listen over stdio yet; flagging that here rather than skipping it.

AI Disclaimer