Resolver takes the extracted _meta directly; trim docstrings

The match-on-params form tripped a 3.10-only branch-coverage quirk on
the case-body fall-through arc. Reading the already-extracted
RequestParamsMeta avoids the match, drops the per-message dict copy, and
keeps a single _meta extraction per request.

Docstrings/comments added in this PR trimmed to one-liners or dropped
where the test/function name already says it.

Author: maxisbey

src/mcp/server/connection.py

@@ -87,9 +87,7 @@ class Connection:
     """The protocol version negotiated during `initialize`; `None` before
     initialization. Stateless connections don't require the handshake, so this
     normally stays `None` there (a client that sends `initialize` anyway still
-    commits it). For the version that applies to the current request - which is
-    always set, including on stateless connections - read
-    `ctx.protocol_version` instead."""
+    commits it). For the per-request value, read `ctx.protocol_version`."""
 
     initialized: anyio.Event
     """Set when `notifications/initialized` arrives (matches TS `oninitialized`);

src/mcp/server/runner.py

@@ -82,28 +82,21 @@ def _extract_meta(params: Mapping[str, Any] | None) -> RequestParamsMeta | None:
 
 def _resolve_protocol_version(
     negotiated: str | None,
-    params: Mapping[str, Any] | None,
+    meta: RequestParamsMeta | None,
     md: MessageMetadata,
 ) -> str:
-    """Resolve the protocol version that applies to this inbound message.
-
-    A handshake-committed value governs the whole connection when present.
-    Otherwise the per-request signals apply: `_meta` (2026-07-28+), then the
-    transport's hint (the validated `MCP-Protocol-Version` header on
-    streamable HTTP). Values outside `SUPPORTED_PROTOCOL_VERSIONS` are
-    skipped so an unrecognized declaration falls through rather than poisons
-    surface validation. The literal terminal default is the last
-    handshake-based revision and is fixed regardless of LATEST bumps.
+    """Resolve the protocol version for this inbound message.
+
+    Handshake-committed value wins; else per-request `_meta`, else the
+    transport hint. Unsupported values fall through so surface validation
+    never sees them.
     """
     if negotiated is not None:
         return negotiated
-    match params:
-        case {"_meta": {**meta}}:
-            v = meta.get(PROTOCOL_VERSION_META_KEY)
-            if isinstance(v, str) and v in SUPPORTED_PROTOCOL_VERSIONS:
-                return v
-        case _:
-            pass
+    if meta is not None:
+        v = meta.get(PROTOCOL_VERSION_META_KEY)
+        if isinstance(v, str) and v in SUPPORTED_PROTOCOL_VERSIONS:
+            return v
     if isinstance(md, ServerMessageMetadata):
         hint = md.protocol_version
         if hint is not None and hint in SUPPORTED_PROTOCOL_VERSIONS:
@@ -250,8 +243,9 @@ async def _on_request(
         method: str,
         params: Mapping[str, Any] | None,
     ) -> dict[str, Any]:
-        version = _resolve_protocol_version(self.connection.protocol_version, params, dctx.message_metadata)
-        ctx = self._make_context(dctx, _extract_meta(params), version)
+        meta = _extract_meta(params)
+        version = _resolve_protocol_version(self.connection.protocol_version, meta, dctx.message_metadata)
+        ctx = self._make_context(dctx, meta, version)
         is_spec_method = method in _methods.SPEC_CLIENT_METHODS
 
         async def _inner() -> HandlerResult:
@@ -318,8 +312,9 @@ async def _on_notify(
         method: str,
         params: Mapping[str, Any] | None,
     ) -> None:
-        version = _resolve_protocol_version(self.connection.protocol_version, params, dctx.message_metadata)
-        ctx = self._make_context(dctx, _extract_meta(params), version)
+        meta = _extract_meta(params)
+        version = _resolve_protocol_version(self.connection.protocol_version, meta, dctx.message_metadata)
+        ctx = self._make_context(dctx, meta, version)
 
         async def _inner() -> None:
             if method in _methods.SPEC_CLIENT_NOTIFICATION_METHODS:

src/mcp/server/session.py

@@ -55,11 +55,8 @@ def client_params(self) -> types.InitializeRequestParams | None:
     def protocol_version(self) -> str | None:
         """The protocol version negotiated during `initialize`.
 
-        `None` before initialization completes. Stateless connections don't
-        require the handshake, so this is normally `None` there. For the
-        version that applies to the current request - which is always set,
-        including on stateless connections - read `ctx.protocol_version`
-        instead.
+        `None` before initialization, and normally `None` on stateless
+        connections. For the per-request value, read `ctx.protocol_version`.
         """
         return self._connection.protocol_version
 

src/mcp/shared/message.py

@@ -35,9 +35,8 @@ class ServerMessageMetadata:
     # transports, None for stdio). Typed as Any because the server layer is
     # transport-agnostic.
     request_context: Any = None
-    # Protocol version the transport derived for this inbound message (the
-    # validated `MCP-Protocol-Version` header on streamable HTTP). `None` when
-    # the transport has no per-message version signal.
+    # Per-message protocol version observed by the transport (e.g. the
+    # validated MCP-Protocol-Version header).
     protocol_version: str | None = None
     # Callback to close SSE stream for the current request without terminating
     close_sse_stream: CloseSSEStreamCallback | None = None

tests/server/test_runner.py

@@ -43,6 +43,7 @@
     PaginatedRequestParams,
     ProgressNotificationParams,
     RequestParams,
+    RequestParamsMeta,
     SetLevelRequestParams,
     Tool,
 )
@@ -654,69 +655,49 @@ async def on_roots(ctx: Ctx, params: NotificationParams | None) -> None:
 
 
 def test_resolve_protocol_version_handshake_committed_value_wins():
-    """A handshake-committed version governs the whole connection; per-request
-    `_meta` and the transport hint are ignored."""
     md = ServerMessageMetadata(protocol_version="2025-03-26")
-    params = {"_meta": {PROTOCOL_VERSION_META_KEY: "2025-03-26"}}
-    assert _resolve_protocol_version("2025-06-18", params, md) == "2025-06-18"
+    meta: RequestParamsMeta = {PROTOCOL_VERSION_META_KEY: "2025-03-26"}
+    assert _resolve_protocol_version("2025-06-18", meta, md) == "2025-06-18"
 
 
 def test_resolve_protocol_version_reads_per_request_meta_when_no_handshake():
-    """With no handshake, a supported `_meta` value is the answer (even with a
-    transport hint also present)."""
     md = ServerMessageMetadata(protocol_version="2025-03-26")
-    params = {"_meta": {PROTOCOL_VERSION_META_KEY: "2025-06-18"}}
-    assert _resolve_protocol_version(None, params, md) == "2025-06-18"
+    meta: RequestParamsMeta = {PROTOCOL_VERSION_META_KEY: "2025-06-18"}
+    assert _resolve_protocol_version(None, meta, md) == "2025-06-18"
 
 
 def test_resolve_protocol_version_skips_unsupported_meta_value():
-    """A `_meta` value the SDK does not serve falls through to the transport
-    hint rather than poisoning surface validation."""
     md = ServerMessageMetadata(protocol_version="2025-03-26")
-    params = {"_meta": {PROTOCOL_VERSION_META_KEY: "1900-01-01"}}
-    assert _resolve_protocol_version(None, params, md) == "2025-03-26"
+    meta: RequestParamsMeta = {PROTOCOL_VERSION_META_KEY: "1900-01-01"}
+    assert _resolve_protocol_version(None, meta, md) == "2025-03-26"
 
 
 def test_resolve_protocol_version_skips_non_string_meta_value():
     md = ServerMessageMetadata(protocol_version="2025-03-26")
-    params: dict[str, Any] = {"_meta": {PROTOCOL_VERSION_META_KEY: 42}}
-    assert _resolve_protocol_version(None, params, md) == "2025-03-26"
+    meta: RequestParamsMeta = {PROTOCOL_VERSION_META_KEY: 42}
+    assert _resolve_protocol_version(None, meta, md) == "2025-03-26"
 
 
 def test_resolve_protocol_version_reads_transport_hint_when_no_handshake_or_meta():
-    """The streamable-HTTP header path: stateless connection, no `_meta`."""
     md = ServerMessageMetadata(protocol_version="2025-06-18")
-    assert _resolve_protocol_version(None, {"name": "x"}, md) == "2025-06-18"
     assert _resolve_protocol_version(None, None, md) == "2025-06-18"
+    assert _resolve_protocol_version(None, {}, md) == "2025-06-18"
 
 
 def test_resolve_protocol_version_skips_unsupported_transport_hint():
-    """The transport may pass through an unvalidated value (the raw `initialize`
-    params version on streamable HTTP); a value the SDK does not serve falls
-    through to the terminal default."""
+    """The `initialize` params version reaches the metadata unvalidated; surface validation must never see it."""
     md = ServerMessageMetadata(protocol_version="1900-01-01")
     assert _resolve_protocol_version(None, None, md) == "2025-11-25"
 
 
 def test_resolve_protocol_version_terminal_default_with_no_signals():
-    """stdio and in-memory transports attach no metadata; before the handshake
-    only `ping` and `initialize` reach the runner, and both exist at the last
-    handshake-based revision."""
     assert _resolve_protocol_version(None, None, None) == "2025-11-25"
-    assert _resolve_protocol_version(None, {}, None) == "2025-11-25"
     assert _resolve_protocol_version(None, None, ServerMessageMetadata()) == "2025-11-25"
     assert _resolve_protocol_version(None, None, ClientMessageMetadata()) == "2025-11-25"
 
 
-def test_resolve_protocol_version_ignores_non_mapping_meta():
-    assert _resolve_protocol_version(None, {"_meta": "oops"}, None) == "2025-11-25"
-
-
 @pytest.mark.anyio
 async def test_runner_ctx_protocol_version_is_terminal_default_on_stateless_in_memory(server: SrvT):
-    """In-memory transport attaches no per-message metadata, so on a stateless
-    connection `ctx.protocol_version` is the resolver's terminal default while
-    the handshake-only `ctx.session.protocol_version` stays `None`."""
     async with connected_runner(server, initialized=False, stateless=True) as (client, runner):
         await client.send_raw_request("tools/list", None)
     ctx = _seen_ctx[0]

tests/shared/test_streamable_http.py

@@ -1371,10 +1371,7 @@ async def stateless_context_app() -> AsyncIterator[Starlette]:
 async def test_streamablehttp_stateless_ctx_protocol_version_tracks_the_header(
     stateless_context_app: Starlette, header_value: str | None, expected: str
 ) -> None:
-    """A stateless server has no handshake-committed version; the validated
-    `MCP-Protocol-Version` header reaches the handler as `ctx.protocol_version`
-    (with the spec's `2025-03-26` default when absent) while the handshake-only
-    `ctx.session.protocol_version` stays `None`."""
+    """No handshake on stateless: the header (or the spec's 2025-03-26 default) reaches `ctx.protocol_version`."""
     body = JSONRPCRequest(
         jsonrpc="2.0",
         id=1,