Server-side 2026-07-28 stateless support: classifier, driver split, server/discover
Implements server-side support for the 2026-07-28 stateless streamable-HTTP path, removing server-stateless from the conformance expected-failures baseline (25/25 checks pass).
Part of #2891. Touches #2892, #2893, #2895, #2896.
Motivation and Context
The 2026-07-28 protocol revision drops the initialize handshake on streamable HTTP: each POST is self-describing (protocol version, client info, client capabilities ride in params._meta) and the server responds with a single JSON-RPC reply. Getting there cleanly meant separating "what handles a request" from "what owns the connection lifecycle" — the existing code threaded a stateless: bool flag through several layers and re-derived per-connection facts in multiple places.
What changed
Kernel/driver split. ServerRunner is now a pure handler kernel (server, connection, lifespan_state → on_request/on_notify). Three free-function drivers compose it with a transport: serve_one (single exchange), serve_connection (caller-supplied dispatcher), serve_loop (stream-pair convenience; what Server.run() and the stateful HTTP path now call).
Connection owns per-peer state. Two factories — from_envelope for the per-request stateless path, for_loop for handshake-driven connections. protocol_version: str is non-Optional and factory-populated; the previous or "2025-11-25" fallbacks and the 17-line resolver are gone. _NoChannelOutbound makes "no back-channel" a property of the held object, not a mode flag — stateless: bool is removed from ServerRunner, ServerSession, and Server.run().
Inbound classifier. shared/inbound.py is a pure validation ladder (envelope shape → header/body match → version supported) returning a typed verdict; ERROR_CODE_HTTP_STATUS is the single code→status table the HTTP entry reads.
Modern HTTP entry. _streamable_http_modern.handle_modern_request is the per-POST path: parse → classify → Connection.from_envelope → serve_one → status-mapped response. The session manager routes by header: known initialize-handshake versions go to the legacy transport; everything else (including unrecognised versions) goes to the modern entry where the classifier validates.
Lifespan owned once. StreamableHTTPSessionManager.run() enters app.lifespan once at startup for both stateful and stateless modes; the stateful path now drives via serve_loop with that state instead of re-entering per session.
server/discover. Auto-derived from registered handlers; a 2025 client gets METHOD_NOT_FOUND from the method/version map, not from a version check in the handler body.
@mcp.tool() exception handling. MCPError (and subclasses) raised from a tool body now propagates as a top-level JSON-RPC error instead of being wrapped as isError: true content — generalising the existing special-case for UrlElicitationRequiredError.
Client. The streamable-HTTP client now parses JSON-RPC error bodies on 4xx responses (so the typed error reaches the caller instead of a generic HTTP exception).
How Has This Been Tested?
server-statelessconformance scenario: 25/25 at the pinned harness, removed from both expected-failures baselines./scripts/test: 100% branch coverage,strict-no-covercleantests/shared/test_inbound.pycovers the classifier exhaustively;tests/interaction/transports/test_hosting_http_modern.pypins the wire contract end to end- Runtime-driven: modern + legacy paths exercised via the in-process ASGI fixture (405 verb mismatch, parse/invalid-request split, header mismatch, unsupported version, handler exception, exit-stack cleanup raise/hang)
Breaking Changes
All documented in docs/migration.md:
Server.run()no longer takesstateless: boolStatelessModeNotSupportedremoved → callers catchNoBackChannelError- Streamable HTTP
lifespanis entered once at manager startup (was per-session/per-request) ServerSessionconstructor signature changed (now(request_outbound, connection))MCPErrorraised from@mcp.tool()now surfaces as a protocol error (wasisError: true)
Types of changes
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing functionality to change)
- Documentation update
Checklist
- I have read the MCP Documentation
- My code follows the repository's style guidelines
- New and existing tests pass locally
- I have added appropriate error handling
- I have added or updated documentation as needed
Additional context
Method-existence is intentionally not a classifier rung — kernel dispatch owns that decision so custom-registered methods route and the answer lives in one place. The modern entry takes the spec's "cannot accept" branch for notification POSTs (400 + INVALID_REQUEST); the core protocol defines no client→server notifications over HTTP at this revision (cancellation is SSE-stream close).