René's URL Explorer Experiment

Title: Resolve protocol version per request and expose it as ctx.protocol_version by maxisbey · Pull Request #2886 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Resolve protocol version per request and expose it as ctx.protocol_version by maxisbey · Pull Request #2886 · modelcontextprotocol/python-sdk

X Title: Resolve protocol version per request and expose it as ctx.protocol_version by maxisbey · Pull Request #2886 · modelcontextprotocol/python-sdk

Description: Adds ctx.protocol_version: str — the protocol version a request is being served at — resolved per request and always set, including on stateless connections. Motivation and Context Since #2849, the runner's inbound surface validation (validate_client_request/validate_client_notification) and outbound result serialization are version-keyed, and they need a version on every request. Today the only source is Connection.protocol_version, which is set by the initialize handshake — so on stateless streamable-HTTP connections it stays None for the connection's whole life and the runner falls back to a hard-coded "2025-11-25". The streamable HTTP transport already reads and validates the MCP-Protocol-Version header per request, but only uses it for transport-local SSE-priming/close-callback gating and then drops it. This threads that value through to the runner and exposes it to handlers as ctx.protocol_version. Resolution rule. A handshake-committed value governs the whole connection when present; otherwise per-request signals apply (_meta["io.modelcontextprotocol/protocolVersion"], then the transport's per-message hint), then the literal 2025-11-25 terminal default. This mirrors the spec's own framing in draft Versioning § Terminology: handshake-based (≤2025-11-25) versions are a connection fact; per-request-metadata (2026-07-28+) versions are a request fact. The resolver doesn't branch on a mode flag — connection.protocol_version is not None is "this connection ran a handshake." Connection.protocol_version and ServerSession.protocol_version keep their existing meaning ("the version negotiated by initialize, None if no handshake ran"); their docstrings now point at ctx.protocol_version for the per-request value. How Has This Been Tested? Unit tests for _resolve_protocol_version covering negotiated-wins, _meta, transport-hint, unsupported-value fall-through, and the terminal default. connected_runner tests for ctx.protocol_version on stateful (negotiated) and stateless in-memory (terminal default, with ctx.session.protocol_version still None). End-to-end streamable-HTTP tests: a stateless server's handler observes ctx.protocol_version matching the request's MCP-Protocol-Version header (parametrized over two values), and the spec's 2025-03-26 default when the header is absent. Full suite at 100% coverage; pyright/ruff clean. Breaking Changes ServerRequestContext gains a required protocol_version: str field. The runner always sets it; the only direct constructors were two tests, updated here. ServerMessageMetadata gains an optional protocol_version field (defaults to None). Types of changes Bug fix (non-breaking change which fixes an issue) 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 Values not in SUPPORTED_PROTOCOL_VERSIONS are skipped by the resolver so an unrecognized declaration falls through rather than poisoning surface validation. Explicit UnsupportedProtocolVersionError rejection for _meta (and the header/_meta MUST-match check) belong in the transport and arrive with the 2026-07-28 negotiation work. The or "2025-11-25" fallbacks on the outbound server-to-client paths (ServerSession.send_request, Connection.send_request) are unchanged; those are connection-scoped sends without access to per-request context, and on stateless connections they fail fast with NoBackChannelError anyway.

Open Graph Description: Adds ctx.protocol_version: str — the protocol version a request is being served at — resolved per request and always set, including on stateless connections. Motivation and Context Since #2849, the...

X Description: Adds ctx.protocol_version: str — the protocol version a request is being served at — resolved per request and always set, including on stateless connections. Motivation and Context Since #2849, the...

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

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width