Retry a tool call once after a HeaderMismatch rejection
Merged
MA
2mo ago+501+501+012345678901234567890123456789-26-26-01234567890123456789
Fixes #3483.
What was wrong
On a 2026-07-28 Streamable HTTP connection, Client.call_tool for a tool with x-mcp-header arguments failed with -32020 (HeaderMismatch) unless that client had already listed the tool. It also kept failing when the tool's schema gained an annotation after it was listed.
The spec's Client Behavior section says a client SHOULD answer that rejection by calling tools/list and retrying the request. The client raised instead. The TypeScript SDK already retries.
What changes
Client.call_tool now performs that recovery. The signature is unchanged and there are no new public names.
- On an
MCPErrorwith code-32020, on a 2026-07-28 connection:- the tool listing is refetched from the server, following cursors until a page lists the tool
- the same call is resent once, with the
Mcp-Param-*headers the current schema asks for
- A second rejection is raised. There is no second retry.
- One timeout bounds the whole re-list, not each page: the
read_timeout_secondspassed tocall_tool, or the client's ownread_timeout_secondswhen none is passed. - If the re-list fails, the original
-32020is raised with that failure as its cause, and the call is not resent. That covers:- an error response, or any other
MCPError - a
tools/listpage that fails validation (pydantic.ValidationError) - the timeout elapsing (
TimeoutError)
- an error response, or any other
What users will notice
- A call that used to raise
-32020because the tool was not listed, or because its schema had changed, now succeeds.- On the wire:
tools/call(rejected),tools/list,tools/call.
- On the wire:
- A
-32020that a re-list cannot cure is still raised, after those extra requests. - The cost of a recovery is one
tools/listrequest per page, up to the page that lists the tool, plus one resend.- For a single-page catalog that is the whole listing, once per recovered call.
- A client that lists tools before calling them never pays it.
- The cursor walk stops after 100 pages, the same cap the server uses when it resolves a tool's schema for this validation. A listing whose cursors never end cannot hang a call: after 100 pages the call is resent once anyway.
- The read timeout in effect (per call, or the client's default) applies separately to the rejected call, to the re-list as a whole, and to the resend, so a recovered call can take up to three times that value.
- With neither set there is no time bound on the re-list, as for any other request; the 100-page cap still applies.
- An
except MCPErroraroundcall_toolsees the-32020in each of those re-list failures; the reason is on__cause__. - Cancelling the caller during a recovery still cancels it.
- The re-list replaces the client's cached tool listing, so a later
list_tools()served from the cache returns the current schema. -32020is a rejection before dispatch, so the resend does not run a tool twice on a conforming server. A tool handler that raises-32020itself is run twice on a 2026-07-28 connection.- Unchanged:
- connections on earlier protocol versions, where a
-32020is raised as it arrives ClientSession.call_tool, which still sends once and leaves the recovery to its caller- every call that does not fail with
-32020
- connections on earlier protocol versions, where a
Docs
- The Header parameters page gains one line saying that a call for a tool the client has not listed is rejected, and that
Clientthen lists the tools and resends it once. - The migration guide's section on
Mcp-Param-*header validation is removed, along with the link to it from the What's new page. The feature is new in 2026-07-28, so it is not a v1-to-v2 migration topic. - The translated pages are not regenerated here; their What's new pages still carry the old link until the next translation run.
Not included
- A public way to pre-load the header map, the other half of the issue. The released spec has only the re-list and retry (the SEP's pre-load note was removed in modelcontextprotocol/modelcontextprotocol#3071), and it would be new public API, so it is out of scope here.
- A warning when a call goes out for a tool the client has not listed.
#3583 moves the code in src/mcp/client/client.py, which this changes (42 lines), so whichever lands second needs a rebase.
How it was checked
- Ten tests in
tests/interaction/transports/test_hosting_http_modern.py, SDK client against SDK server over the in-process HTTP bridge, each asserting the sequence of requests on the wire:- a never-listed tool:
tools/call,tools/list,tools/callwith the header, and the call succeeds (this replaces the test that pinned "one request, raises") - a tool that gains an annotation after it was listed recovers the same way, and the cached listing is replaced
- a mismatch the re-list cannot cure raises
-32020after exactly one retry - a tool on page two: the re-list follows the cursor and stops at that page
- a listing whose cursors never end: 100
tools/listrequests, one resend, then-32020 - a re-list the server refuses: the original
-32020is raised, caused by that error, and nothing is resent - a re-list that returns a malformed page: the same, caused by the
ValidationError - a re-list that never answers, with
read_timeout_secondsset: the same, caused by theTimeoutError(run on a virtual clock, so it takes no real time) - a listing whose cursors never end, each page answered well inside the client's default timeout and no per-call timeout: the re-list is cut off when that one timeout elapses, after three pages, and the original
-32020is raised (also on a virtual clock) - a legacy connection:
-32020is raised with no re-list and no resend
- a never-listed tool:
- The nine 2026-07-28 tests fail on
mainand pass with the change. The legacy test passes on both. - One test in
tests/docs_src/test_header_parameters.pyfor the new docs line: the page's own tutorial server, called without listing first, answers 400 to the firsttools/call, then 200 totools/listand to the resent call withMcp-Param-Region. It fails onmain. - The reproduction from the issue now returns the tool result.
./scripts/testpasses with 100% coverage; ruff and pyright are clean.- The English docs build passes in strict mode, with the render-order and cross-reference checks; markdownlint is clean on the changed pages.
- The conformance suite has no scenario for this SHOULD yet, so the coverage is the SDK's own tests.