First end-to-end 2026-07-28 stateless tools/call (experimental entry + ClientSession pin)

[maxisbey]

First end-to-end slice of the 2026-07-28 stateless protocol, plus the interaction-suite era axis turned on so the existing transport-agnostic tests run at the new revision.

Part of #2891, #2892, #2893, #2894 (closes none).

Server

• mcp.server._streamable_http_modern — handle_modern_request direct-invocation path (private)
• StreamableHTTPSessionManager.handle_request branches on MCP-Protocol-Version ∈ MODERN_PROTOCOL_VERSIONS
• per-request ServerRunner over a SingleExchangeDispatcher (no back-channel; notifications no-op pending the SSE response mode)

Client

• Client, ClientSession, and streamable_http_client() gain protocol_version: str | None
• pinned to "2026-07-28": born initialized (synthesized InitializeResult, placeholder server_info pending server/discover); initialize() is idempotent; stamps the io.modelcontextprotocol/{protocolVersion,clientInfo,clientCapabilities} envelope on every request; cancel_on_abandon=False
• pinned to a stateful version: initialize() requests that version instead of LATEST_PROTOCOL_VERSION
• transport pins MCP-Protocol-Version from the constructor; Mcp-Method/Mcp-Name derived per message; _encode_header_value Base64-sentinel-wraps RFC-7230-unsafe names
• MODERN_PROTOCOL_VERSIONS constant in mcp.shared.version

Types

• CacheableResult defaults to ttl_ms=0, cache_scope="private" so list/read results constructed without explicit hints validate against the 2026-07-28 surface and never accidentally enable shared caching

Interaction suite

• SPEC_VERSIONS = ("2025-11-25", "2026-07-28") — node ids gain a -version suffix
• the connect fixture forwards protocol_version through Client; in-memory and streamable-http-stateless era-locked to 2025-11-25
• [streamable-http-2026-07-28]: 60 pass, 8 xfail (xfails are progress/logging — handler-emitted notifications not yet streamed on the single-exchange path)
• 13 lifecycle:* requirements get removed_in="2026-07-28"; 6 error-shape requirements excluded (modern-error-surface — tests pin the legacy code=0 divergence; the modern arm returns the spec-correct -32603)
• the wire contract (envelope, headers, no handshake, no session-id) stays pinned by transports/test_hosting_http_modern.py

Conformance

• 23 scenarios now pass at the 2026-07-28 wire across the draft and carried-forward legs
• tools-call-with-progress stays expected-fail (progress delivery on the single-exchange path)

Behaviour changes

• ClientSession.initialize() is now idempotent: a second call returns the cached result (or the synthesized one for a stateless pin) instead of re-sending the handshake. All other 2026 behaviour is opt-in via protocol_version=. SUPPORTED_PROTOCOL_VERSIONS and LATEST_PROTOCOL_VERSION are unchanged.

Flagged for review

• 2× # type: ignore[call-arg] in server/session.py for _related_request_id (TODO at :94 — fix is the ServerSession/Context rework)
• 2× # type: ignore[reportPrivateUsage] in the modern entry (_compose_on_request, _EXIT_STACK_CLOSE_TIMEOUT) — both fall out of the ServerRunner driver-split

Out of scope

server/discover, _meta validation ladder, version negotiation, subscriptions/listen, MRTR, SSE response mode for the modern entry, public design of the new HTTP path, in-memory modern entry.

_{AI Disclaimer}

[maxisbey]

seems like we should use the dispatcher context object here then? that's the whole point of it, is it know it's own secret params

[maxisbey]

Agreed it's the wrong shape. Reworded the TODO to point at the actual fix (a per-request Outbound — the DispatchContext — alongside the connection-level one, with related_request_id as the channel selector). That belongs with the ServerSession/Context rework; widening the Protocol is the wrong direction since related_request_id is transport-specific.

[maxisbey]

this is bad

[maxisbey]

Same as above — see the reworded TODO at :94.

[maxisbey]

why?

[maxisbey]

Pinning to a stateful version is the contradiction, not calling initialize() afterward. Tightened the param to Literal["2026-07-28"] (StatelessProtocolVersion) so a 2025-era pin is a type error; the raise stays as the fail-fast for misuse (a no-op would have to synthesize an InitializeResult we don't have).

[maxisbey]

this doesn't seem very high level? why is it being ran like this?

[maxisbey]

Dropped this file (and the MockTransport one) in 194f225. The capstone in transports/test_hosting_http_modern.py proves everything they did at higher altitude — envelope, headers, no-initialize, and now caller-_meta-preserved via a server-side ctx.meta echo. The initialize()-raises and session-id-ignore checks moved to tests/client/.

[claude]

🔴 When a stateful pin (e.g. Client(url, protocol_version="2025-06-18")) is set, the new early return in _maybe_extract_protocol_version_from_message keeps the transport stamping MCP-Protocol-Version with the pinned value even after the server negotiates a different (older) version — a scenario this PR explicitly supports and tests at the session layer. The spec requires subsequent HTTP requests to carry the negotiated version, and the SDK becomes internally inconsistent (session.protocol_version reports the negotiated value while the wire header reports the pin). Consider gating the pin-wins early return on the pin being in MODERN_PROTOCOL_VERSIONS, where no InitializeResult ever exists.

Extended reasoning...

What the bug is. StreamableHTTPTransport now accepts protocol_version at construction, and _maybe_extract_protocol_version_from_message returns early whenever self.protocol_version is not None ("Constructor pin wins over snooping the InitializeResult"). That early return is correct for the stateless 2026-07-28 pin, where no initialize handshake (and hence no InitializeResult) ever exists. But the same constructor pin is also used for stateful pins: Client.__post_init__ forwards protocol_version unconditionally to streamable_http_client(...), and the interaction-suite connect_over_streamable_http factory does the same. So a client pinned to e.g. 2025-06-18 builds a transport whose snoop is permanently disabled.

The code path that triggers it. ClientSession.initialize() with a stateful pin still runs the handshake, requesting the pinned version. The PR explicitly supports the server answering with a different (older) supported version: test_initialize_on_a_stateful_pin_requests_the_pinned_version has the server respond 2025-03-26 to a 2025-06-18 pin, the session accepts it, and session.protocol_version reports the negotiated 2025-03-26. Meanwhile, in the transport, _handle_json_response / _handle_sse_event call _maybe_extract_protocol_version_from_message for the initialization response — but the pin makes it a no-op, so self.protocol_version stays 2025-06-18. _prepare_headers() then sets MCP-Protocol-Version: 2025-06-18 on every subsequent POST/GET/DELETE.

Step-by-step proof.

1. Client("https://server/mcp", protocol_version="2025-06-18") → __post_init__ calls streamable_http_client(url, protocol_version="2025-06-18") → StreamableHTTPTransport(url, protocol_version="2025-06-18"), so transport.protocol_version == "2025-06-18" from construction.
2. Client.__aenter__ builds ClientSession(..., protocol_version="2025-06-18") and calls initialize(). Since "2025-06-18" not in MODERN_PROTOCOL_VERSIONS, the handshake runs and requests protocolVersion: "2025-06-18".
3. The server only supports up to 2025-03-26 and answers InitializeResult(protocolVersion="2025-03-26", ...). 2025-03-26 is in SUPPORTED_PROTOCOL_VERSIONS, so the session accepts it; session.protocol_version now returns 2025-03-26 (exactly what the new test asserts).
4. The transport receives that InitializeResult and calls _maybe_extract_protocol_version_from_message, which returns immediately because self.protocol_version is already "2025-06-18".
5. Every subsequent request — tools/list, tools/call, the standalone GET stream, the closing DELETE — goes out via _prepare_headers() with MCP-Protocol-Version: 2025-06-18, a version the server never negotiated.

Why nothing else prevents it. The only pin-wins test (test_constructor_pin_is_not_overwritten_by_an_initialize_result) and the constructor docstring ("Required for stateless 2026-07-28 sessions") both target the 2026 stateless pin; nothing covers or pins the stateful behavior. The session layer and the transport layer each track their own version with no reconciliation.

Impact. The streamable-HTTP spec requires the client to send the protocol version negotiated during initialization on subsequent HTTP requests, so the header carries a non-negotiated value — a spec violation against stricter servers, which may reject the requests outright (this SDK's own server only checks the header is a supported version, so the failure mode is interop with third-party servers). Even when nothing rejects, the SDK is internally inconsistent: session.protocol_version says 2025-03-26 while the wire says 2025-06-18.

How to fix. Gate the early return on the pin being a modern (stateless) version, e.g. if self.protocol_version is not None and self.protocol_version in MODERN_PROTOCOL_VERSIONS: return — for stateful pins the snoop should still capture the negotiated version (or, equivalently, let the InitializeResult overwrite the pin). This keeps the stateless 2026-07-28 path untouched while restoring spec-correct headers after a downgrade negotiation. The trigger is narrow (a stateful pin plus a server that downgrades), but the pin plumbing is introduced by this PR, so it is worth fixing here.

[claude]

🔴 handle_modern_request validates every POST body strictly as JSONRPCRequest, so a well-formed JSON-RPC notification (no id) is answered with HTTP 400 + a JSONRPCError(PARSE_ERROR) body — the server responds to a notification and mislabels valid JSON as a parse error, while the legacy transport answers the same POST with 202 and no body. Since the pinned client silently swallows the 400, notifications sent via send_progress_notification/send_roots_list_changed on a 2026-07-28 session are dropped invisibly; consider widening the parse to JSONRPCRequest | JSONRPCNotification and answering notifications with 202/no-op (or rejecting them deliberately without a Parse-error envelope).

Extended reasoning...

The bug. In handle_modern_request the request body is parsed with JSONRPCRequest.model_validate_json(body). JSONRPCRequest declares id: RequestId as required (src/mcp/types/jsonrpc.py), so any well-formed JSON-RPC notification — a valid object that simply has no id member — raises ValidationError and falls into the except branch, which answers with HTTP 400 and a JSONRPCError(id=null, code=PARSE_ERROR, message="Parse error") body. Two things are wrong with that: the body is syntactically valid JSON-RPC (it just isn't a request), so -32700 Parse error is a misclassification; and JSON-RPC 2.0 forbids sending a response to a notification, while this path emits a JSON-RPC error envelope for one.\n\nReachability from the SDK's own client. This is not a purely hypothetical peer. A ClientSession pinned to 2026-07-28 still exposes send_notification, send_progress_notification, and send_roots_list_changed, and the pinned StreamableHTTPTransport explicitly supports notifications on this path: _per_message_headers derives Mcp-Method for JSONRPCNotification (and the new transport unit tests pin that behaviour for notifications/cancelled). Because the pinned transport stamps MCP-Protocol-Version: 2026-07-28 on every POST, StreamableHTTPSessionManager.handle_request routes the notification to handle_modern_request, where it hits the 400/Parse-error branch.\n\nStep-by-step proof. (1) Build a pinned client: streamable_http_client(url, protocol_version="2026-07-28") + ClientSession(read, write, protocol_version="2026-07-28"). (2) Call await session.send_progress_notification("tok", 0.5). (3) The transport POSTs {"jsonrpc": "2.0", "method": "notifications/progress", "params": {...}} with MCP-Protocol-Version: 2026-07-28 and Mcp-Method: notifications/progress. (4) The manager sees the modern version header and calls handle_modern_request. (5) JSONRPCRequest.model_validate_json fails on the missing id, so the server returns 400 with {"jsonrpc": "2.0", "id": null, "error": {"code": -32700, "message": "Parse error"}}. (6) On the client, _handle_post_request only emits an error frame for JSONRPCRequest messages when status >= 400, so for a notification the 400 is swallowed and the call returns as if the notification was delivered. By contrast, the legacy streamable-HTTP transport answers the identical notification-only POST with 202 and no body — so this is a behavioural divergence introduced by the new entry, and the loss is invisible to the caller.\n\nWhy nothing else prevents it. The module's TODO ladder covers Accept-header validation and GET/DELETE rejection, not notification bodies, and the interaction-suite exclusion (protocol:progress:client-to-server excluded at 2026-07-28 with reason requires-session) only removes the test, it does not make the wire response correct. The docstring's "one JSON-RPC request in, one JSON-RPC response out" describes the happy path, not a decision to answer notifications with a Parse-error envelope.\n\nOn the counter-argument. One reviewer noted that the streamable-HTTP transport spec permits an HTTP error status (optionally with an id-less JSON-RPC error body) when the server cannot accept a notification POST, and that client-originated notifications are arguably out of scope for this slice. Even granting both points, the response is still wrong on its own terms: -32700 Parse error asserts the body could not be parsed, which is false (the appropriate shape would be an Invalid Request / deliberate not-supported rejection, or simply a 202 no-op as the legacy path does), and the silent client-side swallow means real SDK calls (send_progress_notification, send_roots_list_changed) disappear with no signal anywhere. The fix is small and local — widen the parse to JSONRPCRequest | JSONRPCNotification and answer notifications with 202/no body (matching legacy and the dispatcher's existing notify() no-op), or return a deliberate, correctly-coded rejection.\n\nImpact and fix. Without a change, any 2026-07-28 deployment that uses progress or roots-changed notifications loses them silently and emits a spec-questionable wire response that other-SDK clients may log or mishandle. Suggested fix in handle_modern_request: try JSONRPCRequest, fall back to JSONRPCNotification; for a notification, return Response(status_code=202) (the SingleExchangeDispatcher.notify path already no-ops, pending the SSE response mode), reserving the 400/Parse-error answer for genuinely unparseable bodies.

[claude]

🟡 Pinning protocol_version="2026-07-28" on a Client constructed with a Server/MCPServer instance silently produces a broken session: the pin only flows into streamable_http_client for URL servers, while the in-memory transport still drives the legacy stateful server, so the born-initialized session never sends initialize/notifications/initialized and every call fails with an opaque "Invalid request parameters" error. Since the in-memory modern entry is out of scope for this PR, consider a constructor-time fail-fast (raise when a MODERN_PROTOCOL_VERSIONS pin is combined with a non-URL server) or a docstring restriction on the new protocol_version field.

Extended reasoning...

What happens

Client.__post_init__ (src/mcp/client/client.py:112-118) only forwards protocol_version into streamable_http_client(...) when server is a URL string. When server is a Server/MCPServer instance it builds InMemoryTransport(self.server, ...) with no version awareness — but __aenter__ still passes protocol_version into ClientSession. With a 2026-07-28 pin that session is "born initialized": initialize() returns the locally-synthesized result without ever touching the wire, and no notifications/initialized is sent.

Why every call then fails

InMemoryTransport._connect runs the lowlevel server via actual_server.run(...) with the default stateless=False, so the legacy init gate in ServerRunner._on_request applies: any non-ping request before initialize/notifications/initialized is rejected with MCPError(INVALID_PARAMS, "Invalid request parameters"). The per-request io.modelcontextprotocol/protocolVersion envelope the pinned session stamps does not help — 2026-07-28 is not in SUPPORTED_PROTOCOL_VERSIONS, and the init gate is independent of version resolution anyway.

Step-by-step proof

1. server = MCPServer("test") with an add tool (the exact pattern in the Client class docstring example).
2. async with Client(server, protocol_version="2026-07-28") as client: — __post_init__ wraps server in InMemoryTransport (no version pin); __aenter__ builds a stateless-pinned ClientSession and calls initialize(), which returns the synthesized result without sending any frame. The context manager enters successfully.
3. await client.call_tool("add", {"a": 1, "b": 2}) — the request reaches the lowlevel server's ServerRunner._on_request; connection.initialize_accepted is false (no handshake ever happened), so the gate raises INVALID_PARAMS and the user sees MCPError: Invalid request parameters — an error that points nowhere near the actual cause (an unsupported transport/version combination chosen at construction).

Why nothing prevents it today

Nothing in Client.__post_init__ rejects or warns about the combination, and the new Client.protocol_version docstring describes the stateless behaviour generically ("Pinning to 2026-07-28 or later selects the stateless transport era...") with HTTP only mentioned as an additional detail — while the class's own primary docstring example is exactly the in-memory MCPServer case. The PR description lists the in-memory modern entry as out of scope, and the interaction suite era-locks in-memory to 2025-11-25 in TRANSPORT_SPEC_VERSIONS, so the gap is known internally — but the public API surface gives the user no signal.

Impact and suggested fix

This is not silent corruption — the first call fails loudly — but the failure is confusing and far removed from the cause, on a brand-new public parameter whose docstring invites exactly this usage. A cheap, non-breaking guard fixes it: in __post_init__, raise (e.g. ValueError) when protocol_version in MODERN_PROTOCOL_VERSIONS and server is a Server/MCPServer instance (or, more conservatively, any non-URL transport), with a message pointing at the missing in-memory modern entry. Alternatively, restrict the pin to URL/HTTP servers in the protocol_version docstring until the in-memory modern entry lands.