Evict cached x-mcp-header map when a re-list drops the tool

list_tools only overwrote the cache on the kept path, so if a tool was first
listed with valid x-mcp-header annotations and a later list returned the same
name with invalid ones, the tool was dropped but its stale arg->header map
survived -- a subsequent tools/call would still mirror the old Mcp-Param-*
headers. Evict the entry on the drop path so the cache reflects the last
list_tools entry. Found by Codex review.

Author: Kludex

src/mcp/client/session.py

@@ -786,6 +786,9 @@ async def list_tools(self, *, params: types.PaginatedRequestParams | None = None
             for tool in result.tools:
                 if (reason := find_invalid_x_mcp_header(tool.input_schema)) is not None:
                     logger.warning("dropping tool %r: invalid x-mcp-header (%s)", tool.name, reason)
+                    # Evict any map cached from a prior valid listing so a stale entry can't
+                    # mirror headers for a tool this listing dropped.
+                    self._x_mcp_header_maps.pop(tool.name, None)
                     continue
                 # Cache the arg→header map so a later tools/call mirrors it into Mcp-Param-* headers.
                 self._x_mcp_header_maps[tool.name] = x_mcp_header_map(tool.input_schema)

tests/client/test_client.py

@@ -504,6 +504,38 @@ async def on_list_tools(
         assert [t.name for t in result.tools] == ["ok", "dropme"]
 
 
+@pytest.mark.anyio
+async def test_modern_list_tools_evicts_header_map_when_a_tool_turns_invalid() -> None:
+    """A re-list that drops a previously valid tool must also evict its cached `x-mcp-header` map,
+    so a later `tools/call` can't mirror stale `Mcp-Param-*` headers for a now-dropped tool."""
+    valid = types.Tool(
+        name="run",
+        input_schema={"type": "object", "properties": {"a": {"type": "string", "x-mcp-header": "Region"}}},
+    )
+    invalid = types.Tool(
+        name="run",
+        input_schema={"type": "object", "properties": {"a": {"type": "string", "x-mcp-header": "bad name"}}},
+    )
+    listings = iter([valid, invalid])
+
+    async def on_list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[next(listings)])
+
+    server = Server("test", on_list_tools=on_list_tools)
+
+    with anyio.fail_after(5):
+        async with Client(server) as client:
+            session = client.session
+            await client.list_tools()
+            assert session._resolve_param_headers("run", {"a": "x"}) == {"Mcp-Param-Region": "x"}
+
+            result = await client.list_tools()
+            assert [t.name for t in result.tools] == []
+            assert session._resolve_param_headers("run", {"a": "x"}) == {}
+
+
 def test_client_rejects_handshake_era_mode_at_construction() -> None:
     """A handshake-era protocol-version string passed as `mode=` is rejected by
     `__post_init__` with a hint to use `mode='legacy'` — the version-pin path is