Route unrecognised protocol-version headers to the modern entry; swap header-mismatch ahead of version-supported

The conformance harness sends header=v999.0.0 (matching the body) to trigger
UnsupportedProtocolVersionError, and header=2026 with body=v999 to trigger
HeaderMismatch. With the manager only routing on header in MODERN_PROTOCOL_VERSIONS,
the first case fell through to the legacy stateful path and never reached the
classifier; with the classifier checking version-supported before header-match,
the second case returned -32022 instead of -32020.

Manager now routes any non-legacy header value to the modern entry (the
classifier owns rejection of unknown versions). Classifier now checks
header-body agreement before version-supported, so a client that disagrees
with itself is told so rather than told its body version is unsupported.

Also: 3 dead test-helper lines (registered-but-never-invoked handler bodies
and a never-read property on a stub) replaced per the testing-standards
convention.

Author: maxisbey

src/mcp/server/streamable_http_manager.py

@@ -28,7 +28,7 @@
 from mcp.shared._compat import resync_tracer
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import MODERN_PROTOCOL_VERSIONS
+from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
 from mcp.types import DEFAULT_NEGOTIATED_VERSION, INVALID_REQUEST, ErrorData, JSONRPCError
 
 if TYPE_CHECKING:
@@ -162,11 +162,14 @@ async def handle_request(self, scope: Scope, receive: Receive, send: Send) -> No
         if self._task_group is None:
             raise RuntimeError("Task group is not initialized. Make sure to use run().")
 
-        # TODO(L08): header-only routing for now; body-primary classification
-        # is a follow-up. 2025 paths below remain unchanged.
+        # TODO(L49): header-only era-routing for now; body-primary classification
+        # is a follow-up. The legacy paths below own only the known
+        # initialize-handshake versions; anything else (including unknown
+        # values) goes to the modern entry so the classifier can validate it
+        # and return a structured rejection. 2025 paths below remain unchanged.
         header = MCP_PROTOCOL_VERSION_HEADER.encode("ascii")
         pv = next((v.decode("latin-1") for k, v in scope["headers"] if k == header), None)
-        if pv in MODERN_PROTOCOL_VERSIONS:
+        if pv is not None and pv not in SUPPORTED_PROTOCOL_VERSIONS:
             await handle_modern_request(self.app, self.security_settings, self._lifespan_state, scope, receive, send)
             return
 

src/mcp/shared/inbound.py

@@ -93,12 +93,14 @@ def classify_inbound_request(
     1. ``params._meta`` is a mapping carrying every reserved envelope key
        (protocol version, client info, client capabilities) → else
        :data:`~mcp.types.jsonrpc.INVALID_PARAMS`.
-    2. The envelope's protocol version is in ``supported_modern_versions`` →
+    2. When ``headers`` is given, its ``MCP-Protocol-Version`` entry equals
+       the envelope's protocol version → else
+       :data:`~mcp.types.jsonrpc.HEADER_MISMATCH`. Runs before the
+       supported-version rung so a client that disagrees with itself is told
+       so, rather than told the body's version is unsupported.
+    3. The envelope's protocol version is in ``supported_modern_versions`` →
        else :data:`~mcp.types.jsonrpc.UNSUPPORTED_PROTOCOL_VERSION` with
        ``data = {"supported": [...], "requested": <value>}``.
-    3. When ``headers`` is given, its ``MCP-Protocol-Version`` entry equals
-       the envelope's protocol version → else
-       :data:`~mcp.types.jsonrpc.HEADER_MISMATCH`.
 
     Method existence is *not* a rung: kernel dispatch owns that decision so
     custom-registered methods route and the answer lives in one place.
@@ -123,19 +125,19 @@ def classify_inbound_request(
             "client-capabilities envelope keys",
         )
 
+    if headers is not None and headers.get(MCP_PROTOCOL_VERSION_HEADER) != protocol_version:
+        return InboundLadderRejection(
+            code=HEADER_MISMATCH,
+            message=f"{MCP_PROTOCOL_VERSION_HEADER} header does not match the request envelope's protocol version",
+        )
+
     if protocol_version not in supported_modern_versions:
         return InboundLadderRejection(
             code=UNSUPPORTED_PROTOCOL_VERSION,
             message="Unsupported protocol version",
             data={"supported": list(supported_modern_versions), "requested": protocol_version},
         )
 
-    if headers is not None and headers.get(MCP_PROTOCOL_VERSION_HEADER) != protocol_version:
-        return InboundLadderRejection(
-            code=HEADER_MISMATCH,
-            message=f"{MCP_PROTOCOL_VERSION_HEADER} header does not match the request envelope's protocol version",
-        )
-
     return InboundModernRoute(
         protocol_version=protocol_version,
         client_info=client_info,

tests/interaction/transports/test_hosting_http.py

@@ -14,9 +14,14 @@
 
 from mcp.server import Server, ServerRequestContext
 from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared.version import MODERN_PROTOCOL_VERSIONS
 from mcp.types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CLIENT_INFO_META_KEY,
     INVALID_PARAMS,
     PARSE_ERROR,
+    PROTOCOL_VERSION_META_KEY,
+    UNSUPPORTED_PROTOCOL_VERSION,
     CallToolRequestParams,
     CallToolResult,
     EmptyResult,
@@ -155,7 +160,12 @@ async def test_malformed_and_batched_bodies_return_400() -> None:
 @requirement("hosting:http:protocol-version-400")
 @requirement("hosting:http:protocol-version-default")
 async def test_protocol_version_header_is_validated() -> None:
-    """An unsupported MCP-Protocol-Version header returns 400; an absent header is accepted as the default."""
+    """An unsupported MCP-Protocol-Version header returns 400; an absent header is accepted as the default.
+
+    An unrecognised header value routes to the modern entry (which owns rejection of unknown
+    versions), and a request without the per-request envelope is rejected at the first ladder
+    rung. Only known initialize-handshake versions and an absent header reach the legacy path.
+    """
     async with mounted_app(_server()) as (http, _):
         session_id = await initialize_via_http(http)
 
@@ -172,9 +182,7 @@ async def test_protocol_version_header_is_validated() -> None:
         )
 
     assert bad.status_code == 400
-    assert JSONRPCError.model_validate_json(bad.text).error.message.startswith(
-        "Bad Request: Unsupported protocol version: 1991-01-01."
-    )
+    assert JSONRPCError.model_validate_json(bad.text).error.code == INVALID_PARAMS
     # 202 proves the request was accepted under the assumed default version (2025-03-26).
     assert defaulted.status_code == 202
 
@@ -185,18 +193,27 @@ async def test_unsupported_protocol_version_rejection_body_contains_the_sniffed_
 
     SDK-defined: other SDKs detect this rejection by substring-matching ``Unsupported protocol
     version`` in the response body, so the literal must survive any rewording of the surrounding
-    message. Asserted at the wire because the SDK client never surfaces the rejection body.
+    message. The unsupported value must appear in both the header and the envelope so the
+    classifier reaches its version-supported rung rather than reporting a header mismatch first.
     """
+    bad = "1991-01-01"
+    meta = {
+        PROTOCOL_VERSION_META_KEY: bad,
+        CLIENT_INFO_META_KEY: {"name": "t", "version": "0"},
+        CLIENT_CAPABILITIES_META_KEY: {},
+    }
     async with mounted_app(_server()) as (http, _):
-        session_id = await initialize_via_http(http)
         response = await http.post(
             "/mcp",
-            json={"jsonrpc": "2.0", "id": 2, "method": "ping"},
-            headers=base_headers(session_id=session_id) | {"mcp-protocol-version": "1991-01-01"},
+            json={"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {"_meta": meta}},
+            headers=base_headers() | {"mcp-protocol-version": bad},
         )
 
     assert response.status_code == 400
+    error = JSONRPCError.model_validate_json(response.text).error
+    assert error.code == UNSUPPORTED_PROTOCOL_VERSION
     assert "Unsupported protocol version" in response.text
+    assert error.data == {"supported": list(MODERN_PROTOCOL_VERSIONS), "requested": bad}
 
 
 @requirement("hosting:http:json-response-mode")

tests/interaction/transports/test_hosting_http_modern.py

@@ -157,14 +157,12 @@ async def test_modern_initialize_is_method_not_found() -> None:
 
 
 @requirement("hosting:http:modern:legacy-fallthrough")
-async def test_non_modern_version_header_falls_through_to_legacy_transport_unchanged() -> None:
-    """The 2026-07-28 routing branch fires only on its exact header; everything else reaches legacy.
-
-    SDK-defined under the draft versioning rules: the modern entry must not change any 2025-era
-    byte. A 2025-era initialize on the same endpoint still completes (legacy serves it), and an
-    unrecognised ``MCP-Protocol-Version`` still falls through to the legacy gate and produces the
-    ``Unsupported protocol version`` literal that peer SDKs substring-sniff. Asserted at the wire
-    because the literal is only observable in the raw response body.
+async def test_legacy_version_header_falls_through_and_unrecognised_header_routes_to_modern() -> None:
+    """SDK-defined under the draft versioning rules: only the known initialize-handshake protocol
+    versions reach the legacy transport, so a 2025-era ``initialize`` on the same endpoint still
+    completes unchanged. Any other ``MCP-Protocol-Version`` value routes to the modern entry,
+    where the validation ladder rejects it (a request without the per-request envelope fails the
+    first rung). The modern entry is therefore the single owner of unknown-version rejection.
     """
     async with mounted_app(_server()) as (http, _):
         # 2025-era initialize through the same endpoint: the modern branch must not intercept it.
@@ -176,7 +174,7 @@ async def test_non_modern_version_header_falls_through_to_legacy_transport_uncha
         )
 
     assert unrecognised.status_code == 400
-    assert "Unsupported protocol version" in unrecognised.text
+    assert JSONRPCError.model_validate_json(unrecognised.text).error.code == INVALID_PARAMS
 
 
 @requirement("hosting:http:modern:handler-exception-internal-error")

tests/server/lowlevel/test_server_discover.py

@@ -98,12 +98,12 @@ async def test_capabilities_derived_from_registered_handlers() -> None:
     async def list_tools(
         ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
     ) -> types.ListToolsResult:
-        return types.ListToolsResult(tools=[])
+        raise NotImplementedError
 
     async def list_prompts(
         ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
     ) -> types.ListPromptsResult:
-        return types.ListPromptsResult(prompts=[])
+        raise NotImplementedError
 
     server = Server("cap-server", on_list_tools=list_tools)
 

tests/server/test_runner.py

@@ -1304,10 +1304,7 @@ class _StubDispatchContext:
     transport: TransportContext = field(default_factory=lambda: TransportContext(kind="direct", can_send_request=False))
     message_metadata: MessageMetadata = None
     cancel_requested: anyio.Event = field(default_factory=anyio.Event)
-
-    @property
-    def can_send_request(self) -> bool:
-        return self.transport.can_send_request
+    can_send_request: bool = False
 
     async def send_raw_request(
         self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None

tests/shared/test_inbound.py

@@ -172,10 +172,12 @@ def test_classifier_passes_unknown_method_through_to_route(method: str) -> None:
 
 
 def test_ladder_first_failure_wins() -> None:
-    """Spec-mandated: rungs evaluate in order — version and header would both fail; the version rung fires."""
+    """Spec-mandated: rungs evaluate in order — header-mismatch and version-unsupported
+    would both fail; the header rung fires first so an inconsistent client is told it
+    disagrees with itself rather than that its body version is unsupported."""
     body = envelope(version=LATEST_PROTOCOL_VERSION)
     result = classify_inbound_request(body, headers={MCP_PROTOCOL_VERSION_HEADER: MODERN})
-    assert_rejected(result, UNSUPPORTED_PROTOCOL_VERSION)
+    assert_rejected(result, HEADER_MISMATCH)
 
 
 # --- ERROR_CODE_HTTP_STATUS ----------------------------------------------------