Skip to content

Streamable HTTP serves a 2026-07-28 request as legacy when the MCP-Protocol-Version header is 2025-era or missing #3863

Open

Description

@juanluisdb

Initial Checks

Release line

2.x

Description

StreamableHTTPSessionManager picks the protocol era from the MCP-Protocol-Version header alone. A request can carry the 2026-07-28 _meta envelope in its body while its header says 2025-11-25, or has no header at all. Either way it goes to the legacy path and gets HTTP 200 with a 2025-shaped result.

The Protocol Version Header section says the header must match _meta's io.modelcontextprotocol/protocolVersion, and the server "MUST reject the request with 400 Bad Request and a HeaderMismatch JSON-RPC error" when it doesn't.

Running the script in Example Code prints:

2026-07-28 200 {"jsonrpc":"2.0","id":1,"result":{"cacheScope":"private","resultType":"complete","tools":[
2025-11-25 200 {"jsonrpc":"2.0","id":1,"result":{"tools":[{"description":"","inputSchema":{"properties":{
None 200 {"jsonrpc":"2.0","id":1,"result":{"tools":[{"description":"","inputSchema":{"properties":{

The last two are answered as 2025 requests. I'd expect 400 with error -32020.

I had a look at how this could work. The routing is header-only on purpose for now (the TODO in _handle_request), but most of the pieces seem to be there already. The stdio runner picks the era from the body (_has_modern_envelope), and classify_inbound_request already answers a missing or different header with HEADER_MISMATCH. So maybe HTTP could use the same body check before falling back to legacy, roughly:

 # StreamableHTTPSessionManager._handle_request
 if pv is not None and pv not in HANDSHAKE_PROTOCOL_VERSIONS:
     await handle_modern_request(...)
     return
+if scope["method"] == "POST":
+    # body is already buffered by RequestBodyLimitMiddleware
+    message = await receive()
+    receive = replay(message, then=receive)
+    body = parse_json_or_none(message["body"])
+    if isinstance(body, dict) and body.get("method") != "initialize" and has_modern_envelope(body.get("params")):
+        await handle_modern_request(..., receive, send)  # existing ladder -> 400 / -32020
+        return
 if self.stateless:
     ...

-# runner.py
-def _has_modern_envelope(params): ...
+# shared/inbound.py, used by both stdio and HTTP
+def has_modern_envelope(params): ...

That keeps legacy traffic (including unparseable bodies) on the same path as today. A couple of questions before I go further:

  • Should batches and notifications that carry the 2026-07-28 _meta be covered too, like the TypeScript SDK does? I kept them out of the sketch to keep it small.
  • Is the TODO(L49) follow-up already planned on your side? If so, I'm happy to leave it with you.

If this direction makes sense, I'm happy to open a PR for it. Ofc I've used Claude to work on this issue. The repro, the testing and any mistakes are all mine.

Example Code

# uv run --with mcp repro.py
import threading
import time

import httpx2
import uvicorn

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("repro")


@mcp.tool()
def ping() -> str:
    return "pong"


app = mcp.streamable_http_app(stateless_http=True, json_response=True)
server = uvicorn.Server(uvicorn.Config(app, port=8765, log_level="warning"))
threading.Thread(target=server.run, daemon=True).start()
while not server.started:
    time.sleep(0.1)

body = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
        "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientCapabilities": {},
        }
    },
}

for version in ["2026-07-28", "2025-11-25", None]:
    headers = {"accept": "application/json", "mcp-method": "tools/list"}
    if version:
        headers["mcp-protocol-version"] = version
    response = httpx2.post("http://127.0.0.1:8765/mcp", json=body, headers=headers)
    print(version, response.status_code, response.text[:90])

Python & MCP Python SDK

Python 3.13.0
mcp 2.3.0 (also reproduced on main at 77001c9)

Activity

  1. added
    bugSomething isn't working
    spec-2026-07-28Concerns the SDK's implementation of the 2026-07-28 MCP spec revision
    v2Affects the v2 line (2.x on main)
    on Nov 16, 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

    bugSomething isn't workingspec-2026-07-28Concerns the SDK's implementation of the 2026-07-28 MCP spec revisionv2Affects the v2 line (2.x on main)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions