René's URL Explorer Experiment

Title: Server-side 2026-07-28 stateless support: classifier, driver split, server/discover by maxisbey · Pull Request #2928 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Server-side 2026-07-28 stateless support: classifier, driver split, server/discover by maxisbey · Pull Request #2928 · modelcontextprotocol/python-sdk

X Title: Server-side 2026-07-28 stateless support: classifier, driver split, server/discover by maxisbey · Pull Request #2928 · modelcontextprotocol/python-sdk

Description: 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-stateless conformance scenario: 25/25 at the pinned harness, removed from both expected-failures baselines ./scripts/test: 100% branch coverage, strict-no-cover clean tests/shared/test_inbound.py covers the classifier exhaustively; tests/interaction/transports/test_hosting_http_modern.py pins 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 takes stateless: bool StatelessModeNotSupported removed → callers catch NoBackChannelError Streamable HTTP lifespan is entered once at manager startup (was per-session/per-request) ServerSession constructor signature changed (now (request_outbound, connection)) MCPError raised from @mcp.tool() now surfaces as a protocol error (was isError: 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). AI Disclaimer

Open Graph Description: 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. Touch...

X Description: 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. Touch...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2928

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width