Repository navigation
Description
Initial Checks
- I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
- I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue
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
_metabe 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