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
andrevegas commentedon Nov 17, 2026
Confirming this on mcp 2.3.0 through FastMCP 4.1.7 (
http_app(stateless_http=True)), with a second observable symptom.Header
MCP-Protocol-Version: 2025-11-25plus a 2026-07-28_metaenvelope:tools/listreturns HTTP 200 with a 2025-shaped result, as in the report.server/discoverreturns HTTP 200 with{"error":{"code":-32601,"message":"Method not found","data":"server/discover"}}, because the legacy path has no such method. A conformance probe that sends a modern-only method sees-32601instead of the required 400/-32020.The reverse case (header
2026-07-28, envelope2025-11-25) correctly returns 400 with-32020, so the validation ladder works. Only the era routing in_handle_requestskips it.I could not find a clean workaround outside the SDK. It would have to buffer and replay the POST body, detect the envelope, write the rejection itself, and still sit behind the host application's authentication. That duplicates what
TODO(L49)already describes, so this looks best fixed in the manager, along the lines of the sketch above.Drafted with Claude Code; I reproduced the behaviour and reviewed the text before posting.
Judge an enveloped initialize against its header, and update the rout…
Route Streamable HTTP era from the request envelope, not only the header
Judge an enveloped initialize against its header, and update the rout…