Retry a tool call once after a HeaderMismatch rejection

docs/advanced/header-parameters.md

@@ -13,6 +13,7 @@ The mark is one extra key in the argument's JSON Schema. On `MCPServer`, `Field`
 ```
 
 * Over Streamable HTTP on `2026-07-28`, a client that has listed the tool sends `Mcp-Param-Region` alongside the body, and the server rejects a call where the two disagree.
+* A client that hasn't listed the tool yet sends no header, and the call is rejected. This SDK's `Client` then lists the tools and resends the call once, so listing first only saves a round trip.
 * Every other connection ignores the annotation.
 
 Your function doesn't change: `region` still arrives as an argument.

docs/migration.md

@@ -2865,14 +2865,6 @@ On a 2026-07-28 connection, `notifications/tools/list_changed`, `notifications/p
 
 Migrate to publishing on the subscription bus, which stamps and filters per stream: `await ctx.notify_tools_changed()`, `notify_prompts_changed()`, `notify_resources_changed()`, and `notify_resource_updated(uri)` on `MCPServer`'s `Context`, or `await bus.publish(...)` on a low-level `Server`'s own `SubscriptionBus` — see [Subscriptions](handlers/subscriptions.md). A stream only ever receives the kinds and URIs the server acknowledged for it; to gate per caller which subscriptions may be opened, refuse `subscriptions/listen` in a middleware (`MCPServer(middleware=[...])`), covered on the same page.
 
-### Servers validate `Mcp-Param-*` headers against the request body ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243))
-
-On the 2026-07-28 Streamable HTTP path, a `tools/call` whose tool declares `x-mcp-header` annotations is validated before dispatch — each annotated argument and its mirroring `Mcp-Param-*` header must be present together and agree (after base64-sentinel decoding; integers compare numerically), or absent together. A violation is rejected with HTTP 400 and JSON-RPC error `-32020` (`HeaderMismatch`), as the spec requires. A client that sends an annotated argument *without* its header — for example one that never listed the tool — is therefore rejected instead of silently served; the spec's recovery is to re-list and retry. On the client side, `ClientSession.call_tool` emits these headers automatically for annotated arguments of any tool it has listed; list the tool first, and note that pre-2026 connections and non-HTTP transports never emit them.
-
-There is nothing to configure. The server resolves the called tool's schema through its own registered `tools/list` handler (for `MCPServer`, the built-in one), so the validated catalog is exactly what that caller would be shown. Two consequences worth knowing: the listing runs internally on validated calls, so middleware and an expensive or paginated `tools/list` handler see extra invocations; and validation is skipped — never failing the call — when no `tools/list` handler is registered, the tool isn't in the listing, the handler raises (logged as an error), or the call has no arguments and no `Mcp-Param-*` headers. Headers with no matching annotation are ignored; a recognized header supplied more than once is rejected, as is a duplicated `MCP-Protocol-Version`, `Mcp-Method`, or `Mcp-Name` line. The codec and validator are public in `mcp.shared.inbound` (`decode_header_value`, `validate_mcp_param_headers`) for low-level servers hosting their own HTTP entry.
-
-Base64-sentinel decoding is strict everywhere it applies, including the `Mcp-Name` header: a `=?base64?...?=` value whose payload is not canonical base64 (wrong padding, stray characters, non-zero trailing bits) or not valid UTF-8 is rejected as malformed rather than leniently decoded.
-
 ## Need Help?
 
 If you encounter issues during migration:

docs/whats-new.md

@@ -199,7 +199,7 @@ At 2026-07-28 the standalone HTTP GET stream and `resources/subscribe` are repla
 ### The rest, quickly
 
 * **Identity is optional, per-message metadata.** The request-side `clientInfo` `_meta` key is optional (the required pair is `protocolVersion` + `clientCapabilities`), and `serverInfo` moved out of the `server/discover` result body: servers stamp it into every 2026-era result's `_meta` instead ([spec #3002](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3002)). The SDK always stamps; `client.server_info` is `None` when a server does not identify itself (for example, a middleware stripped the key). **[The low-level Server](advanced/low-level-server.md)** shows the stamp on the wire.
-* **Requests are routable without parsing bodies.** Modern HTTP requests carry `Mcp-Method` (and, for the three tool-ish calls, `Mcp-Name`); a tool input-schema property annotated with `x-mcp-header` is mirrored into an `Mcp-Param-*` header and cross-checked by the server ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243)). Gateways and rate limiters can route on headers alone; the **[Migration Guide](migration.md#servers-validate-mcp-param-headers-against-the-request-body-sep-2243)** has the rules.
+* **Requests are routable without parsing bodies.** Modern HTTP requests carry `Mcp-Method` (and, for the three tool-ish calls, `Mcp-Name`); a tool input-schema property annotated with `x-mcp-header` is mirrored into an `Mcp-Param-*` header and cross-checked by the server ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243)). Gateways and rate limiters can route on headers alone.
 * **Results carry cache hints.** List and read results declare `ttlMs` and `cacheScope` ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)); you set them per method with `cache_hints=`, and `Client` honors them with a built-in response cache. A server that sends no hints (every pre-2026 server) sees identical, uncached traffic. **[Caching hints](client/caching.md)**.
 * **Extensions are first class.** Servers and clients declare optional capability bundles under reverse-DNS identifiers ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)); the built-in `Apps` extension (MCP Apps) is the reference. **[Extensions](advanced/extensions.md)** and **[MCP Apps](advanced/apps.md)**.
 * **Error codes got standardized.** A missing resource is `-32602` with the URI in `error.data`, and the new spec-reserved codes appear as `-32020` (header mismatch), `-32021` (missing required capability), and `-32022` (unsupported protocol version). **[Troubleshooting](troubleshooting.md)** is keyed by the exact messages.

src/mcp/client/client.py

@@ -8,12 +8,13 @@
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
 from dataclasses import KW_ONLY, dataclass, field
-from typing import Any, Literal, TypeVar, cast
+from typing import Any, Final, Literal, TypeVar, cast
 
 import anyio
 import anyio.lowlevel
 import mcp_types as types
 from mcp_types import (
+    HEADER_MISMATCH,
     INVALID_PARAMS,
     CacheableResult,
     CallToolResult,
@@ -40,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
@@ -79,6 +81,9 @@
 initialize), or a modern protocol-version string (adopt directly). The ``str`` arm is for
 forward-compat; ``Client.__post_init__`` rejects anything outside that set at construction."""
 
+_RELIST_PAGE_CAP: Final = 100
+"""Page cap for the tools/list walk that follows a `HEADER_MISMATCH`: a paginator that never ends cannot hang a call."""
+
 _T = TypeVar("_T")
 _ResultT = TypeVar("_ResultT")
 _CacheableT = TypeVar("_CacheableT", bound=CacheableResult)
@@ -775,10 +780,17 @@ async def call_tool(
         exceptions propagate as-is. To receive the claimed shape yourself, use
         `client.session.call_tool(..., allow_claimed=True)`.
 
+        On a 2026-07-28 connection, a call the server rejects with `HEADER_MISMATCH`
+        (this client has not listed the tool, or its input schema changed since) is
+        resent once after refetching the tool listing. A second rejection is raised,
+        and so is the first when the listing cannot be refetched.
+
         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`. Defaults to this
+                client's `read_timeout_seconds`.
             progress_callback: Callback for progress updates.
             input_responses: Responses to seed the first call with (e.g. when
                 resuming from a persisted `InputRequiredResult`).
@@ -795,7 +807,7 @@ async def call_tool(
                 conform to the negotiated protocol version.
         """
 
-        async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult | Result:
+        async def send(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult | Result:
             return await self.session.call_tool(
                 name,
                 arguments,
@@ -809,6 +821,21 @@ async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | Inp
                 allow_claimed=True,
             )
 
+        async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult | Result:
+            try:
+                return await send(r, s)
+            except MCPError as mismatch:
+                if mismatch.code != HEADER_MISMATCH or self.protocol_version not in MODERN_PROTOCOL_VERSIONS:
+                    raise
+                # The spec's recovery: the tool's listed schema is missing or stale, so re-list and resend once.
+                timeout = read_timeout_seconds if read_timeout_seconds is not None else self.read_timeout_seconds
+                try:
+                    with anyio.fail_after(timeout):
+                        await self._relist_tool(name)
+                except (MCPError, TimeoutError, ValidationError) as relist_error:
+                    raise mismatch from relist_error
+                return await send(r, s)
+
         result = await self._drive_input_required(await retry(input_responses, request_state), retry)
         if isinstance(result, CallToolResult):
             return result
@@ -943,6 +970,15 @@ async def list_tools(
             ),
         )
 
+    async def _relist_tool(self, name: str) -> None:
+        """Refetch the tool listing from the server, page by page, until a page lists `name`."""
+        cursor: str | None = None
+        for _ in range(_RELIST_PAGE_CAP):
+            page = await self.list_tools(cursor=cursor, cache_mode="refresh")
+            cursor = page.next_cursor
+            if cursor is None or any(tool.name == name for tool in page.tools):
+                return
+
     @deprecated("The roots capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def send_roots_list_changed(self) -> None:
         """Send a notification that the roots list has changed."""

tests/docs_src/test_header_parameters.py

@@ -63,6 +63,31 @@ async def test_a_call_whose_header_and_body_disagree_is_rejected() -> None:
     assert tampered.json()["error"]["code"] == HEADER_MISMATCH
 
 
+async def test_a_client_that_has_not_listed_the_tool_is_rejected_then_lists_and_resends_once() -> None:
+    """tutorial001: the first call has no header and is a 400; after one `tools/list` it is resent with the header."""
+    app = tutorial001.mcp.streamable_http_app()
+    exchanges: list[tuple[str, str | None, int]] = []
+
+    async def record(response: httpx2.Response) -> None:
+        sent = response.request.headers
+        exchanges.append((sent["mcp-method"], sent.get("mcp-param-region"), response.status_code))
+
+    async with (
+        app.router.lifespan_context(app),
+        httpx2.ASGITransport(app) as transport,
+        httpx2.AsyncClient(transport=transport, event_hooks={"response": [record]}) as http,
+        Client(streamable_http_client(URL, http_client=http)) as client,
+    ):
+        result = await client.call_tool("check_stock", ARGUMENTS)
+    assert result.structured_content == {"result": "Dune: 3 copies in eu."}
+    assert exchanges == [
+        ("server/discover", None, 200),
+        ("tools/call", None, 400),
+        ("tools/list", None, 200),
+        ("tools/call", "eu", 200),
+    ]
+
+
 async def test_a_legacy_http_connection_ignores_the_annotation() -> None:
     """tutorial001: before 2026-07-28 the same call succeeds and carries no `Mcp-Param-*` header."""
     async with check_stock_over_http(tutorial001.mcp.streamable_http_app(), mode="legacy") as (_, call):

tests/interaction/_requirements.py

@@ -3624,6 +3624,17 @@ def __post_init__(self) -> None:
         transports=("streamable-http",),
         note="Only observable over streamable HTTP: headers are derived from the cached tool schema at the seam.",
     ),
+    "client-transport:http:header-mismatch-recovery": Requirement(
+        source=f"{SPEC_2026_BASE_URL}/basic/transports/streamable-http#client-behavior",
+        behavior=(
+            "When the server rejects a tools/call with HeaderMismatch, the client calls tools/list for the "
+            "tool's current inputSchema and retries the call once with the Mcp-Param-* headers that schema "
+            "asks for. A second rejection is raised to the caller."
+        ),
+        added_in="2026-07-28",
+        transports=("streamable-http",),
+        note="Client.call_tool only: ClientSession.call_tool sends once and leaves the recovery to its caller.",
+    ),
     "client-transport:http:vendor-name-param-header": Requirement(
         source="sdk",
         behavior=(