You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 72bd9f3
Browse filesBrowse the repository at this point in the historyBrowse files
Judge an enveloped initialize against its header, and update the routing docs
An `initialize` carrying the reserved 2026-07-28 version key with a 2025-era
or missing header was still served by the legacy handshake, so the same body
got a successful handshake or a modern rejection depending only on the
header. A handshake never carries the reserved key, so route it like any
other enveloped request and let the modern entry answer HeaderMismatch.
Ordinary legacy `initialize` requests are unchanged and covered by tests.
Document that routing now also considers the 2026-07-28 envelope.
Refs #3863
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/run/deploy.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,7 +70,7 @@ Four processes, one socket. And now the question every deployment has to answer:
70
70
71
71
For a client speaking the **2026-07-28** protocol, no. A modern request is one self-contained POST: no `initialize` handshake before it, no `Mcp-Session-Id` on the response, nothing for a second request to come back *to*. Route it to any worker.
72
72
73
-
That is not a mode you switch on. `stateless_http=True` looks like it should be, but the transport routes on the `MCP-Protocol-Version` request header, hands a modern request to the modern handler, and **returns**. The line that reads `stateless_http` comes *after* that return. It isn't that the flag is ignored on the 2026-07-28 path; it is never reached. `stateless_http` is a knob for the **legacy** leg only, and the modern path is sessionless by construction.
73
+
That is not a mode you switch on. `stateless_http=True` looks like it should be, but the transport routes on the `MCP-Protocol-Version` request header (and the request's `_meta` envelope), hands a modern request to the modern handler, and **returns**. The line that reads `stateless_http` comes *after* that return. It isn't that the flag is ignored on the 2026-07-28 path; it is never reached. `stateless_http` is a knob for the **legacy** leg only, and the modern path is sessionless by construction.
74
74
75
75
For a legacy client on spec version 2025-11-25 or earlier, the answer depends on that flag:
Copy file name to clipboardExpand all lines: docs/run/legacy-clients.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ MCP has two protocol eras: the `initialize`-handshake era, up to spec version `2
4
4
5
5
This page is about the server side of that split, and the answer fits in one sentence: **the `streamable_http_app()` you already deploy serves both.**
6
6
7
-
The SDK routes every request by its `MCP-Protocol-Version` header. A request naming `2026-07-28`goes to the modern handler. A request naming a handshake-era version, or carrying no header at all (which is how a pre-2026 client's `initialize` arrives), goes to the transport those clients expect: `initialize` handshake, sessions and all. It happens per request, before your code, on the one app.
7
+
The SDK routes every request by its `MCP-Protocol-Version` header and its body. A request naming `2026-07-28`, or carrying the 2026-07-28 `_meta` envelope, goes to the modern handler; if such a request's header is missing or names another version, it is rejected with `400` and `HeaderMismatch` (`-32020`). Any other request naming a handshake-era version, or carrying no header at all (which is how a pre-2026 client's `initialize` arrives), goes to the transport those clients expect: `initialize` handshake, sessions and all. It happens per request, before your code, on the one app.
8
8
9
9
So a legacy client is not something you build *for*. It is something that connects *to* the server you already wrote. You configure nothing.
10
10
@@ -163,7 +163,7 @@ Two lines, no `if`, no version check, and you are done. That is the entire list
163
163
164
164
## Recap
165
165
166
-
* One `streamable_http_app()` serves both protocol eras. The SDK routes each request by its `MCP-Protocol-Version` header; there is nothing to configure and no era knob to look for.
166
+
* One `streamable_http_app()` serves both protocol eras. The SDK routes each request by its `MCP-Protocol-Version` header and, for requests carrying the 2026-07-28 envelope, its body; there is nothing to configure and no era knob to look for.
167
167
* A legacy client costs you a session: an in-process `Mcp-Session-Id` record with no distributed store behind it. More than one worker means **sticky routing**, or the wrong worker answers `404 Session not found`. **[Deploy & scale](deploy.md)** has the multi-worker story.
168
168
*`stateless_http=True` is the one knob, and it is **legacy-leg-only**. It buys free load balancing for legacy clients at the price of both server-to-client channels on that leg: server-initiated requests raise `NoBackChannelError` (a top-level error at the client, not an `is_error` result), and notifications are dropped.
169
169
* A `2026-07-28` connection is sessionless either way. `stateless_http` never touches it.
0 commit comments