Restore pv header on dispatcher-written POSTs; widen auto-mode probe fallback

The streamable-HTTP transport now clears its cached MCP-Protocol-Version
header when an initialize POST goes out, then lets every other POST read
the cache again (re-collapsing _base_headers into _prepare_headers).
This restores the header on JSON-RPC response/error/cancelled POSTs the
dispatcher writes without per-message metadata, while still preventing a
discover-probe value from leaking onto a fallback initialize.

Client(mode='auto') now also falls back to initialize() when the probe
is rejected with INVALID_REQUEST — what a deployed v1.x stateful (or
stateless) streamable-HTTP server returns for a session-id-less request
or an unknown protocol-version header. The lifecycle:discover requirement
text is updated to match.

Author: maxisbey

src/mcp/client/client.py

@@ -24,6 +24,7 @@
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
 from mcp.types import (
+    INVALID_REQUEST,
     METHOD_NOT_FOUND,
     REQUEST_TIMEOUT,
     CallToolResult,
@@ -252,7 +253,9 @@ async def __aenter__(self) -> Client:
                 try:
                     await session.discover()
                 except MCPError as e:
-                    if e.code in (METHOD_NOT_FOUND, REQUEST_TIMEOUT):
+                    # TODO(L73): invert this allowlist into a `classify_probe_outcome` denylist —
+                    # fall back on every rpc-error/4xx that isn't a recognized modern error.
+                    if e.code in (METHOD_NOT_FOUND, INVALID_REQUEST, REQUEST_TIMEOUT):
                         await session.initialize()
                     else:
                         raise

src/mcp/client/streamable_http.py

@@ -81,33 +81,28 @@ def __init__(self, url: str) -> None:
         """
         self.url = url
         self.session_id: str | None = None
-        # Captured from the first stamped POST's metadata; reused on transport-internal
-        # GET/DELETE that don't carry per-message metadata.
+        # Captured from each stamped POST's metadata. Reused on outbound HTTP that carries
+        # no per-message header (transport-internal GET/DELETE, and dispatcher-written
+        # response/error/cancel POSTs that bypass the session's stamp). Cleared when an
+        # `initialize` POST goes out so a probe-stamped value cannot leak onto the handshake.
         self._protocol_version_header: str | None = None
 
-    def _base_headers(self) -> dict[str, str]:
-        """Build MCP-specific request headers (accept / content-type / session-id).
-
-        These headers will be merged with the httpx.AsyncClient's default headers,
-        with these MCP-specific headers taking precedence. POSTs use this directly:
-        their protocol-version header arrives per-message via ``metadata.headers``,
-        so they must never read the cached value.
+    def _prepare_headers(self) -> dict[str, str]:
+        """Build MCP-specific request headers for any outbound HTTP request.
+
+        These are merged with the ``httpx.AsyncClient`` defaults (these take
+        precedence). The cached ``MCP-Protocol-Version`` is included whenever
+        present so messages that don't pass through the session's stamp —
+        response/error/cancel POSTs, transport-internal GET/DELETE — still
+        carry the negotiated version. Per-message headers are layered on top
+        by the caller.
         """
         headers: dict[str, str] = {
             "accept": "application/json, text/event-stream",
             "content-type": "application/json",
         }
         if self.session_id:
             headers[MCP_SESSION_ID] = self.session_id
-        return headers
-
-    def _prepare_headers(self) -> dict[str, str]:
-        """Base headers plus the cached protocol-version header.
-
-        Used by transport-internal GET/DELETE (listen stream, resumption,
-        reconnect, terminate) which don't carry per-message metadata.
-        """
-        headers = self._base_headers()
         if self._protocol_version_header:
             headers[MCP_PROTOCOL_VERSION_HEADER] = self._protocol_version_header
         return headers
@@ -249,13 +244,17 @@ async def _handle_resumption_request(self, ctx: RequestContext) -> None:
 
     async def _handle_post_request(self, ctx: RequestContext) -> None:
         """Handle a POST request with response processing."""
-        headers = self._base_headers()
         message = ctx.session_message.message
+        is_initialization = self._is_initialization_request(message)
+        if is_initialization:
+            # `initialize` is the negotiation, not a "subsequent request" — discard any
+            # probe-stamped value so the discover→fallback path can't leak it onto the handshake.
+            self._protocol_version_header = None
+        headers = self._prepare_headers()
         if ctx.metadata is not None and ctx.metadata.headers is not None:
             headers.update(ctx.metadata.headers)
             if MCP_PROTOCOL_VERSION_HEADER in ctx.metadata.headers:
                 self._protocol_version_header = ctx.metadata.headers[MCP_PROTOCOL_VERSION_HEADER]
-        is_initialization = self._is_initialization_request(message)
 
         async with ctx.client.stream(
             "POST",

tests/client/test_streamable_http.py

@@ -17,7 +17,7 @@
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER, encode_header_value
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
-from mcp.types import METHOD_NOT_FOUND, JSONRPCError, JSONRPCRequest
+from mcp.types import METHOD_NOT_FOUND, JSONRPCError, JSONRPCNotification, JSONRPCRequest, JSONRPCResponse
 
 
 @pytest.mark.parametrize(
@@ -104,19 +104,25 @@ def handler(request: httpx.Request) -> httpx.Response:
 
 
 @pytest.mark.anyio
-async def test_post_does_not_read_cached_protocol_version_header() -> None:
-    """A POST's protocol-version header comes only from its own ``metadata.headers``.
-
-    The first POST carries (and caches) a pv header; the second POST sends no metadata
-    and must therefore carry no pv header — a stale cached value would poison the
-    fallback ``initialize`` after a failed discover probe. The cache exists for
-    transport-internal GET/DELETE only.
+async def test_initialize_post_clears_cached_pv_header_and_unstamped_posts_read_it() -> None:
+    """``initialize`` discards the cached protocol-version header; every other POST reads it.
+
+    Steps:
+    1. A stamped probe POST caches its ``MCP-Protocol-Version`` header.
+    2. An ``initialize`` POST clears that cache before building headers, so the fallback
+       handshake never carries a probe-stamped value.
+    3. A subsequent stamped POST re-seeds the cache with the negotiated version.
+    4. An unstamped POST (a JSON-RPC response written by the dispatcher, which never
+       passes through the session's stamp) then reads the cache and carries the
+       negotiated version — the spec MUST for all post-initialization HTTP requests.
     """
     recorded: list[httpx.Request] = []
 
     def handler(request: httpx.Request) -> httpx.Response:
         recorded.append(request)
         body = json.loads(request.content)
+        if "id" not in body or "result" in body:
+            return httpx.Response(202)
         return httpx.Response(200, json={"jsonrpc": "2.0", "id": body["id"], "result": {}})
 
     with anyio.fail_after(5):
@@ -133,6 +139,18 @@ def handler(request: httpx.Request) -> httpx.Response:
             await read.receive()
             await write.send(SessionMessage(JSONRPCRequest(jsonrpc="2.0", id=2, method="initialize", params={})))
             await read.receive()
-    assert [r.method for r in recorded] == ["POST", "POST"]
+            await write.send(
+                SessionMessage(
+                    message=JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized"),
+                    metadata=ClientMessageMetadata(headers={MCP_PROTOCOL_VERSION_HEADER: "2025-11-25"}),
+                )
+            )
+            # An unstamped JSON-RPC response — what the dispatcher writes when answering
+            # a server-initiated request (sampling/elicitation/roots).
+            await write.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=99, result={})))
+
+    assert [r.method for r in recorded] == ["POST", "POST", "POST", "POST"]
     assert recorded[0].headers[MCP_PROTOCOL_VERSION_HEADER] == "2026-07-28"
     assert MCP_PROTOCOL_VERSION_HEADER not in recorded[1].headers
+    assert recorded[2].headers[MCP_PROTOCOL_VERSION_HEADER] == "2025-11-25"
+    assert recorded[3].headers[MCP_PROTOCOL_VERSION_HEADER] == "2025-11-25"

tests/interaction/_requirements.py

@@ -438,12 +438,13 @@ def __post_init__(self) -> None:
     "lifecycle:discover:network-error-raises": Requirement(
         source="sdk",
         behavior=(
-            "An HTTP timeout, connection error, or non-404 4xx/5xx during server/discover raises to the "
-            "caller without falling back to initialize."
+            "A network/connection error or 5xx during server/discover raises to the caller without "
+            "falling back to initialize. A 4xx with a JSON-RPC error body is a server-side rejection "
+            "and falls back (legacy servers reject the probe with 400 INVALID_REQUEST)."
         ),
         transports=("streamable-http", "streamable-http-stateless"),
         added_in="2026-07-28",
-        note="HTTP-only: distinguishes transport-level failures from the -32601 fallback signal.",
+        note="HTTP-only: distinguishes transport-level failures from server-side rejection.",
     ),
     "lifecycle:mode:legacy-never-probes": Requirement(
         source="sdk",

tests/interaction/lowlevel/test_client_connect.py

@@ -32,6 +32,7 @@
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
     INTERNAL_ERROR,
+    INVALID_REQUEST,
     METHOD_NOT_FOUND,
     PROTOCOL_VERSION_META_KEY,
     UNSUPPORTED_PROTOCOL_VERSION,
@@ -217,7 +218,7 @@ async def discover(ctx: ServerRequestContext, params: types.RequestParams | None
 
 @requirement("lifecycle:discover:network-error-raises")
 async def test_auto_mode_reraises_a_non_fallback_discover_error_without_initializing() -> None:
-    """A `server/discover` failure outside the {-32601, -32001, -32022} ladder raises without falling back.
+    """A `server/discover` failure that is not a recognised legacy-server rejection raises without falling back.
 
     Requirement `lifecycle:discover:network-error-raises` (sdk-defined): a 5xx-class error from
     the probe is surfaced to the caller; the client never sends `initialize`. Exercised here as
@@ -248,14 +249,27 @@ def is_internal_error(exc: MCPError) -> bool:
 
 
 @requirement("lifecycle:discover:fallback-method-not-found")
-async def test_auto_mode_falls_back_to_initialize_when_discover_is_method_not_found() -> None:
-    """A -32601 from `server/discover` makes an auto-negotiating client run the legacy `initialize` handshake.
+@pytest.mark.parametrize(
+    ("probe_code", "probe_message"),
+    [
+        (METHOD_NOT_FOUND, "Method not found"),
+        (INVALID_REQUEST, "Bad Request: Missing session ID"),
+    ],
+    ids=["method-not-found", "invalid-request"],
+)
+async def test_auto_mode_falls_back_to_initialize_on_a_legacy_probe_rejection(
+    probe_code: int, probe_message: str
+) -> None:
+    """A legacy server's rejection of `server/discover` makes an auto-negotiating client fall back to `initialize`.
 
     Requirement `lifecycle:discover:fallback-method-not-found` (spec stdio#backward-compatibility):
     a legacy-era server that does not implement `server/discover` is connected to via the
-    handshake, and the session lands at a handshake-era protocol version. A real `Server` always
-    implements `server/discover`, so this test plays the server's side of the wire by hand.
-    Reserve this pattern for behaviour no real server can be made to produce.
+    handshake, and the session lands at a handshake-era protocol version. The probe rejection
+    arrives as METHOD_NOT_FOUND from a server that routes the unknown method, or as
+    INVALID_REQUEST from a deployed v1.x stateful streamable-HTTP server that rejects the
+    session-id-less probe before dispatch. A real `Server` always implements `server/discover`,
+    so this test plays the server's side of the wire by hand. Reserve this pattern for behaviour
+    no real server can be made to produce.
     """
     methods_seen: list[str] = []
 
@@ -267,7 +281,7 @@ async def scripted_server(streams: MessageStream) -> None:
             assert isinstance(frame, JSONRPCRequest | JSONRPCNotification)
             methods_seen.append(frame.method)
             if isinstance(frame, JSONRPCRequest) and frame.method == "server/discover":
-                error = types.ErrorData(code=METHOD_NOT_FOUND, message="Method not found")
+                error = types.ErrorData(code=probe_code, message=probe_message)
                 await server_write.send(SessionMessage(JSONRPCError(jsonrpc="2.0", id=frame.id, error=error)))
             elif isinstance(frame, JSONRPCRequest) and frame.method == "initialize":
                 result = InitializeResult(