Bound the re-list by the caller's timeout and chain every re-list failure

`read_timeout_seconds` now covers the whole re-list after a
`HeaderMismatch`, which otherwise ran on the session default. When it
elapses, or a `tools/list` page fails validation, the original `-32020`
is raised with that failure as its cause.

Author: maxisbey

src/mcp/client/client.py

@@ -41,6 +41,7 @@
     ServerCapabilities,
 )
 from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
+from pydantic import ValidationError
 from typing_extensions import deprecated
 
 from mcp.client._input_required import DEFAULT_INPUT_REQUIRED_MAX_ROUNDS, run_input_required_driver
@@ -787,7 +788,8 @@ async def call_tool(
         Args:
             name: The name of the tool to call.
             arguments: Arguments to pass to the tool.
-            read_timeout_seconds: Timeout for each underlying `tools/call` round.
+            read_timeout_seconds: Timeout for each underlying `tools/call` round, and
+                for the whole re-list after a `HEADER_MISMATCH`.
             progress_callback: Callback for progress updates.
             input_responses: Responses to seed the first call with (e.g. when
                 resuming from a persisted `InputRequiredResult`).
@@ -826,8 +828,9 @@ async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | Inp
                     raise
                 # The spec's recovery: the tool's listed schema is missing or stale, so re-list and resend once.
                 try:
-                    await self._relist_tool(name)
-                except MCPError as relist_error:
+                    with anyio.fail_after(read_timeout_seconds):
+                        await self._relist_tool(name)
+                except (MCPError, TimeoutError, ValidationError) as relist_error:
                     raise mismatch from relist_error
                 return await send(r, s)
 

tests/interaction/transports/test_hosting_http_modern.py

@@ -42,18 +42,26 @@
     Tool,
 )
 from mcp_types.version import LATEST_MODERN_VERSION
+from pydantic import ValidationError
+from trio.testing import MockClock
 
 from mcp import MCPError
 from mcp.client.client import Client
 from mcp.client.session import ClientSession
 from mcp.client.streamable_http import streamable_http_client
 from mcp.server import Server, ServerRequestContext
+from mcp.server.context import CallNext, HandlerResult
 from tests.interaction._connect import BASE_URL, base_headers, initialize_via_http, mounted_app
 from tests.interaction._requirements import requirement
 
 pytestmark = pytest.mark.anyio
 
 
+@pytest.fixture(autouse=True)
+def _module_runner_lease() -> None:
+    """Opt out of the shared per-module event loop: this module parametrizes `anyio_backend`."""
+
+
 def _modern_headers(*, method: str, name: str | None = None) -> dict[str, str]:
     """Request headers for a 2026-07-28 POST.
 
@@ -778,6 +786,106 @@ async def rewrite_mcp_name(request: httpx2.Request) -> None:
     assert methods == ["tools/call", "tools/list"]
 
 
+@requirement("client-transport:http:header-mismatch-recovery")
+async def test_modern_client_raises_the_header_mismatch_when_the_re_list_returns_a_malformed_page() -> None:
+    """A `tools/list` page that fails validation leaves the caller with the server's `HeaderMismatch`.
+
+    SDK-defined: a caller's `except MCPError` still sees the rejection, with the `ValidationError` as its
+    cause, and the call is not resent. The page comes from a middleware that answers without `call_next`,
+    the one place the SDK server does not validate an outgoing result.
+    """
+
+    async def malformed_listing(ctx: ServerRequestContext, call_next: CallNext) -> HandlerResult:
+        assert ctx.method == "tools/list"
+        return {"tools": "not a list"}
+
+    async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+        raise NotImplementedError
+
+    server = Server("malformed", on_call_tool=call_tool)
+    server.middleware.append(malformed_listing)
+
+    methods: list[str] = []
+
+    async def rewrite_mcp_name(request: httpx2.Request) -> None:
+        method = json.loads(request.content)["method"]
+        methods.append(method)
+        if method == "tools/call":
+            request.headers["mcp-name"] = "another-tool"
+
+    discover = DiscoverResult(
+        supported_versions=[LATEST_MODERN_VERSION],
+        capabilities=ServerCapabilities(),
+    )
+    async with (
+        mounted_app(server, on_request=rewrite_mcp_name) as (http, _),
+        Client(
+            streamable_http_client(f"{BASE_URL}/mcp", http_client=http),
+            mode=LATEST_MODERN_VERSION,
+            prior_discover=discover,
+        ) as client,
+    ):
+        with anyio.fail_after(5), pytest.raises(MCPError) as excinfo:
+            await client.call_tool("run", {"region": "us-west1"})
+
+    assert excinfo.value.error.code == HEADER_MISMATCH
+    assert isinstance(excinfo.value.__cause__, ValidationError)
+    assert methods == ["tools/call", "tools/list"]
+
+
+# The timeout also governs the rejected `tools/call`, which must be answered before the re-list can
+# wait it out, so any real-clock value is a bet against CI scheduler stalls. On trio's autojumping
+# clock time advances only when every task is blocked: the answered call cannot time out however slow
+# the runner, and once the re-list blocks the clock jumps straight to the deadline, with no real wait.
+@requirement("client-transport:http:header-mismatch-recovery")
+@pytest.mark.parametrize(
+    "anyio_backend",
+    [pytest.param(("trio", {"clock": MockClock(autojump_threshold=0)}), id="trio-mockclock")],
+)
+async def test_modern_client_raises_the_header_mismatch_when_the_re_list_outlasts_the_read_timeout() -> None:
+    """The caller's `read_timeout_seconds` bounds the re-list, which otherwise has no timeout of its own.
+
+    SDK-defined: the server rejects the call and then never answers `tools/list`. When the timeout elapses
+    the rejection is raised with the `TimeoutError` as its cause, and the call is not resent.
+    """
+
+    async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+        await anyio.Event().wait()  # blocks until the abandoned request's disconnect interrupts it
+        raise NotImplementedError  # unreachable
+
+    async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+        raise NotImplementedError
+
+    server = Server("stalled", on_list_tools=list_tools, on_call_tool=call_tool)
+
+    methods: list[str] = []
+
+    async def rewrite_mcp_name(request: httpx2.Request) -> None:
+        method = json.loads(request.content)["method"]
+        methods.append(method)
+        if method == "tools/call":
+            request.headers["mcp-name"] = "another-tool"
+
+    discover = DiscoverResult(
+        supported_versions=[LATEST_MODERN_VERSION],
+        capabilities=ServerCapabilities(),
+    )
+    async with (
+        mounted_app(server, on_request=rewrite_mcp_name) as (http, _),
+        Client(
+            streamable_http_client(f"{BASE_URL}/mcp", http_client=http),
+            mode=LATEST_MODERN_VERSION,
+            prior_discover=discover,
+        ) as client,
+    ):
+        with anyio.fail_after(5), pytest.raises(MCPError) as excinfo:
+            await client.call_tool("run", {"region": "us-west1"}, read_timeout_seconds=0.05)
+
+    assert excinfo.value.error.code == HEADER_MISMATCH
+    assert isinstance(excinfo.value.__cause__, TimeoutError)
+    assert methods == ["tools/call", "tools/list"]
+
+
 @requirement("client-transport:http:header-mismatch-recovery")
 async def test_legacy_client_raises_a_header_mismatch_error_without_re_listing_or_retrying() -> None:
     """On a pre-2026 connection a `-32020` error from a tool call is raised as it arrives.