Server-side 2026-07-28 stateless support: classifier, driver split, server/discover

Merged
MA
5mo ago
+2256-1088

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