Skip to content

fix(mcp): serve legacy MCP clients alongside 2026-07-28 - #357

Merged
vishr merged 2 commits into
mainfrom
fix/mcp-dual-era
Oct 19, 2026
Merged

vishr merged 2 commits into
mainfrom
fix/mcp-dual-era

Conversation

@vishr

@vishr vishr commented Oct 19, 2026 •

Copy link
Copy Markdown
Member

Codex CLI 0.163 and other hosts still open with a legacy initialize. The public /mcp endpoint accepted only 2026-07-28, so default Codex failed with -32020: MCP-Protocol-Version header is required. Codex worked only behind its experimental mcp_2026_07_28 flag.

The 2026-07-28 versioning rules allow a dual-era server. A request with modern per-request metadata is served statelessly, and an initialize selects legacy semantics scoped to a session. Fanout now does both on /mcp.

  • Versions: modern 2026-07-28, plus legacy 2025-11-25 and 2025-06-18. 2025-03-26 and 2024-11-05 are not offered because they allow batches; an initialize asking for them negotiates to 2025-11-25.
  • Routing: POST bodies are decoded before routing. Every initialize goes to the legacy session handler. Modern headers or modern _meta select the stateless handler.
  • Legacy sessions: bound to the authenticated user. They expire after 10 idle minutes, with at most eight per user and OAuth client.
  • Security: scope and tool rate checks used to read Mcp-Method and Mcp-Name, which only modern clients send. Accepting legacy clients as-is would have let a telemetry:read token reach dashboard writes and skip the rate limit. Both checks now read the bounded body unless the SDK has verified the modern headers against it. Batches are rejected. Dashboard handlers also enforce dashboard:manage themselves.
  • MCP Apps: UI metadata and app-only tools still go only to clients that declared io.modelcontextprotocol/ui, per the core rule to revert to core behavior. Legacy sessions use the capabilities declared in initialize.
  • 401 challenge: now names scope="telemetry:read".
  • Browser /api/mcp: stays modern-only.
  • Docs: the MCP guide's Protocol section describes the dual-era behavior.

Verification:

  • just check passes.
  • Two Codex adversarial review rounds. The first found that an initialize carrying a modern header was routed to the stateless handler; this is fixed in the second commit with a regression test. The second round approved.
  • New conformance tests cover legacy flows for both versions, dashboard scope in both eras (including forged headers), legacy rate limiting, session identity and termination, the session cap, batch and oversize rejection, MCP Apps gating per era, and the 401 scope.

vishr added 2 commits October 19, 2026 09:04
Codex CLI and other hosts still open with a legacy initialize, which the
public /mcp endpoint rejected. Fanout is now dual-era, as the 2026-07-28
versioning rules allow: modern requests stay stateless, and an initialize
for 2025-11-25 or 2025-06-18 gets a session, so the capabilities a legacy
client declares (including MCP Apps) are known on later requests.

Scope and tool rate checks no longer depend on modern-only headers: they
read the bounded request body for legacy requests and reject batches, so
a read-only token cannot reach dashboard writes over the legacy protocol.
Legacy sessions expire after ten idle minutes, with eight per user and
OAuth client. The 401 challenge names telemetry:read.

Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ
…ader says

The 2026-07-28 versioning rules select legacy semantics for any
initialize. Routing read the header first, so an initialize carrying the
modern header reached the stateless handler and failed. Decode the one
message before routing; scope and rate checks follow the same split.

Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ
@vishr
vishr merged commit e19395a into main Oct 19, 2026
16 checks passed
@vishr
vishr deleted the fix/mcp-dual-era branch October 19, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant