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

[maxisbey]

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}

[claude]

🟡 The auto-derived server/discover handler builds its capabilities via self.get_capabilities() with no arguments, so a lowlevel-Server operator who declares listChanged or experimental capabilities via create_initialization_options(NotificationOptions(...), {...}) will advertise them in the initialize response but not in the server/discover response. Consider threading the stored options through (or storing them on the Server), or explicitly documenting that discover ignores create_initialization_options arguments.

Extended reasoning...

What the bug is. The new default Server._handle_discover (src/mcp/server/lowlevel/server.py:397-413) returns DiscoverResult(capabilities=self.get_capabilities(), ...). With this PR, get_capabilities() defaults notification_options to NotificationOptions() (all list_changed flags False) and experimental_capabilities to None. Meanwhile the legacy initialize path still reports capabilities from InitializationOptions (ServerRunner._handle_initialize uses opts.capabilities), which the operator builds via the documented create_initialization_options(NotificationOptions(tools_changed=True), {\"my-ext\": {...}}). The same server therefore advertises different capabilities depending on which protocol era the client speaks.

Code path / step-by-step proof.

1. An operator constructs a lowlevel Server and calls server.run(read, write, server.create_initialization_options(NotificationOptions(tools_changed=True), {\"my-ext\": {}})) — the existing, documented way to declare listChanged and experimental capabilities.
2. A 2025-era client sends initialize; _handle_initialize returns opts.capabilities → tools.listChanged == true and the experimental block is present.
3. A 2026-era client (or any modern-envelope path) sends server/discover; _handle_discover calls self.get_capabilities() with no arguments → notification_options = NotificationOptions(), experimental_capabilities = None → the response reports tools.listChanged == false and no experimental block.
4. The two advertisements disagree for the same server, and there is no knob to influence the discover-derived capabilities short of replacing the whole handler via add_request_handler(\"server/discover\", ...).

Why existing code doesn't prevent it. _handle_discover structurally cannot see the per-run InitializationOptions — they are a parameter of Server.run()/serve_loop, not server state — so the under-advertisement is baked into the handler's design rather than an accidental wiring miss.

Mitigating factors (why this is filed as a nit, addressing the refutation). The practical blast radius is narrow: every in-tree caller (MCPServer, the SSE app, the stdio __main__, the streamable-HTTP manager) calls create_initialization_options() with no arguments, so initialize and discover agree on all SDK-owned paths; only out-of-tree lowlevel operators who explicitly pass NotificationOptions/experimental are affected. The affected fields are advisory (listChanged hints, experimental block), and on the modern single-exchange HTTP path server notifications are currently dropped anyway (TODO D-005a), so listChanged=False there is arguably the more honest answer. The pre-existing TODO(L53) on get_capabilities already flags that list_changed/experimental should be derived from server state instead of caller-assembled options, and the discover docstring documents the wholesale-override escape hatch. None of that makes the divergence go away, though — the inconsistency is newly introduced by this PR (server/discover is new here) and is user-visible to any client that compares the two advertisements.

Impact. A 2026-era client consuming server/discover from such a server will believe list-changed notifications are not emitted and that no experimental capabilities exist, while a 2025-era client connecting to the same server is told the opposite. Capability-gated client behaviour (subscribing to list-changed, enabling experimental features) silently degrades on the modern path.

How to fix. Either (a) let the Server store NotificationOptions / experimental capabilities (e.g. constructor params, in line with TODO(L53)) and have both create_initialization_options() and _handle_discover read from that single source, or (b) at minimum document on create_initialization_options / the migration guide that arguments passed there do not influence the server/discover response and that operators needing parity must override the handler via add_request_handler(\"server/discover\", ...).

[claude]

🟡 Stale comment: this PR removed the stateless kwarg from Server.run() (and updated this call), but the line above still says "stateless=True so server.run doesn't wait for initialize handshake" — it now describes an argument that no longer exists. Update or delete the comment.

Extended reasoning...

What the issue is. This PR deletes the stateless: bool parameter from the lowlevel Server.run() (see src/mcp/server/lowlevel/server.py and the new migration-guide entry "Server.run() no longer takes a stateless flag"), and the call site in tests/server/test_lowlevel_exception_handling.py was mechanically updated to await server.run(read_recv, write_send, server.create_initialization_options()). The comment immediately above that call, however, was left untouched: # stateless=True so server.run doesn't wait for initialize handshake. The comment now refers to an argument that is neither passed nor accepted anywhere in the API.

Why it's misleading. The comment doesn't just name a removed flag — its rationale no longer describes how the test works. The test pushes a RuntimeError into the read stream and then closes it; server.run() exits because the read side closes, not because an init gate was skipped. No request is ever dispatched, so the initialize handshake is irrelevant to the test's flow either way. A reader trying to understand the new serve_loop-based Server.run() could be misled into believing a stateless mode still exists on the loop driver, when the PR's whole point is that statelessness is now a property of how the Connection is constructed (Connection.from_envelope), not a flag on the loop.

Step-by-step. (1) Before this PR, line 42 read await server.run(..., stateless=True) and the comment on line 40 explained that argument. (2) This PR removes stateless from Server.run()'s signature and edits line 42 to drop the kwarg. (3) Line 40 still says "stateless=True so server.run doesn't wait for initialize handshake", describing code that no longer exists. (4) The test still passes — the exit path is the read-stream close — confirming the comment's rationale is not load-bearing.

Why nothing else catches it. Comments aren't checked by the type checker or tests, and nothing else in the file references the removed flag, so the stale text will persist until someone notices it manually.

How to fix. Delete the line, or replace it with something accurate, e.g. # server.run exits when the read stream yields the exception and then closes. One-line cleanup; behaviour is unaffected, so this is a nit and shouldn't block the PR.