Skip to content

Streamable HTTP: pre-2026 _meta protocolVersion claim on non-initialize requests is routed to serveModern and rejected with 400 #3159

Open

Description

@godavid

Summary

createMcpHandler (with the default legacy: 'stateless') rejects 2025-era requests with HTTP 400 when a non-initialize message carries a pre-2026 io.modelcontextprotocol/protocolVersion claim in params._meta. The legacy path would serve the same request without problems.

Affected: @modelcontextprotocol/server 2.3.1 (via mcp-handler 2.1.1). The same logic is still in 2.4.0.

Reproduction

Use a stateless endpoint built with createMcpHandler(factory) and the default legacy serving. Send this request:

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-06-18

{"jsonrpc":"2.0","id":9,"method":"tools/list","params":{"_meta":{
  "io.modelcontextprotocol/protocolVersion":"2025-06-18",
  "io.modelcontextprotocol/clientInfo":{"name":"t","version":"0"},
  "io.modelcontextprotocol/clientCapabilities":{}}}}

The endpoint answers with this:

HTTP 400
{"jsonrpc":"2.0","error":{"code":-32022,"message":"Unsupported protocol version: 2025-06-18","data":{"supported":["2026-07-28"],"requested":"2025-06-18"}},"id":9}

If the request sends only the version key in _meta, the endpoint answers 400 -32602 Invalid _meta envelope for protocol revision 2026-07-28: io.modelcontextprotocol/clientCapabilities: missing.

Without _meta, the same tools/list succeeds with 200. initialize with the same claim also succeeds: carriesValidModernEnvelopeClaim keeps a pre-2026 claim on the legacy handshake.

Cause

In classifyRequestBody, the hasEnvelopeClaim(params) branch returns kind: "modern" for any claimed version. classificationForClaim then marks the era correctly as legacy. But handle() dispatches on outcome.kind, so the message goes to serveModern, which rejects any revision that is not in SUPPORTED_MODERN_PROTOCOL_VERSIONS. Before that, validateEnvelopeMeta validates the envelope against the 2026-07-28 schema. classifyNotificationBody and classifyBatch (batch-with-modern-element) have the same issue.

initialize routes such claims to the legacy path. Every other method should probably do the same: classify the message as legacy (reason no-claim, with requestedVersion set to the claimed version) whenever the claimed version is not a modern version.

Impact

In production we saw 2025-era clients lose two requests per session this way: init 200, then 400, 202, 400, 200. Over 7 days we logged at least 927 of these errors. As a workaround, we strip the io.modelcontextprotocol/protocolVersion key from _meta when its value is lower than 2026-07-28, before the request reaches the handler.

Activity

  1. media-ctrl commented on Nov 7, 2026

    @media-ctrl
  2. tomwangcn commented on Nov 7, 2026

    @tomwangcn

    Hi, I'd like to work on this one. My read of the current code matches the diagnosis:

    • classifyRequestBody returns kind: 'modern' for any request with an envelope claim, whatever version it names. classificationForClaim does record era: 'legacy' on the classification, but handle() dispatches on outcome.kind, so the request reaches serveModern, which rejects anything not in SUPPORTED_MODERN_PROTOCOL_VERSIONS with -32022 — even on a dual-era endpoint (legacy: 'stateless') that would serve 2025-06-18 fine.
    • The partial-envelope case (only the version key in _meta) is rejected one rung earlier, because validateEnvelopeMeta applies the 2026-07-28 envelope schema to a claim that names a 2025 revision.

    Proposed fix, along the lines you suggest: when the claimed revision is not a modern revision, classify the message as legacy (requestedVersion set to the claimed revision) — the same precedence initialize already gets via carriesValidModernEnvelopeClaim — and skip the modern envelope validation for those claims, since that schema belongs to the modern revision. Claims naming a modern revision are unchanged, including the malformed-envelope rejection, and modern-only endpoints keep answering -32022 (a legacy route with no legacy handler still goes through modernOnlyStrictRejection). Same treatment in classifyNotificationBody and classifyBatch.

    I'll reproduce against current main first, then open a PR with regression tests for the request, notification, and batch cases.

    (Apologies for the deleted comment a minute ago — posted from the wrong account by mistake.)

  3. added
    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
    on Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions