Title: MCPServer has no x-mcp-header declaration mechanism and never validates one, so an invalid annotation is served happily and dropped by every client · Issue #3484 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: MCPServer has no x-mcp-header declaration mechanism and never validates one, so an invalid annotation is served happily and dropped by every client · Issue #3484 · modelcontextprotocol/python-sdk
X Title: MCPServer has no x-mcp-header declaration mechanism and never validates one, so an invalid annotation is served happily and dropped by every client · Issue #3484 · modelcontextprotocol/python-sdk
Description: Summary MCPServer offers no way to mark a tool parameter with x-mcp-header, and does not validate the annotation when one is smuggled in through pydantic. A server author who gets it wrong gets no signal at all: the tool is served happil...
Open Graph Description: Summary MCPServer offers no way to mark a tool parameter with x-mcp-header, and does not validate the annotation when one is smuggled in through pydantic. A server author who gets it wrong gets no ...
X Description: Summary MCPServer offers no way to mark a tool parameter with x-mcp-header, and does not validate the annotation when one is smuggled in through pydantic. A server author who gets it wrong gets no ...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3484
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"MCPServer has no x-mcp-header declaration mechanism and never validates one, so an invalid annotation is served happily and dropped by every client","articleBody":"### Summary\n\n`MCPServer` offers no way to mark a tool parameter with `x-mcp-header`, and does not validate the annotation when one is smuggled in through pydantic. A server author who gets it wrong gets no signal at all: the tool is served happily, and every conforming client silently drops it.\n\nSEP-2243's *Reference Implementation* section names this as a server-SDK requirement:\n\n> * **Server SDKs**: Provide a mechanism (attribute/decorator) for marking parameters with `x-mcp-header`\n> * **Client SDKs**: Implement the client behavior for extracting and encoding header values\n> * **Validation**: Both sides must validate header/body consistency\n\nThe client half is implemented. The server half is not: `x-mcp-header` appears in `mcp/client/session.py`, `mcp/shared/inbound.py` and `mcp_types/_v2026_07_28/`, and **nowhere under `mcp/server/`**.\n\n### 1. No declaration mechanism\n\nThe only route is pydantic passthrough:\n\n```python\n@server.tool()\nasync def fetch(\n owner: Annotated[str, Field(json_schema_extra={\"x-mcp-header\": \"owner\"})],\n) -> str:\n ...\n```\n\nThis works — the annotation reaches `inputSchema`, the client mirrors it, `mcp/shared/inbound.py` validates it — so this is an ergonomics and discoverability gap rather than a functional one. But it means the feature is invisible from the server API, and that a server author must know the extension keyword's exact spelling from the spec.\n\n### 2. Nothing validates the declaration server-side\n\nThis is the part that fails silently. SEP-2243 puts type restrictions on `x-mcp-header` and assigns their enforcement to the server:\n\n> | Test Case | Property Type | x-mcp-header Present | Expected Behavior |\n> | Array type | `\"type\": \"array\"` | Yes | **Server MUST reject tool definition** |\n> | Object type | `\"type\": \"object\"` | Yes | **Server MUST reject tool definition** |\n> | Null type | `\"type\": \"null\"` | Yes | **Server MUST reject tool definition** |\n\n`MCPServer` rejects none of them.\n\n```python\nimport anyio\nfrom typing import Annotated\nfrom pydantic import Field\nfrom mcp.client import Client\nfrom mcp.client._memory import InMemoryTransport\nfrom mcp.server.mcpserver import MCPServer\n\nserver = MCPServer(\"repro\")\n\n@server.tool()\nasync def bad(\n tags: Annotated[list[str], Field(json_schema_extra={\"x-mcp-header\": \"Tags\"})],\n) -> str:\n \"\"\"An array parameter annotated x-mcp-header -- the spec says reject.\"\"\"\n return \"ok\"\n\nasync def main() -> None:\n async with Client(InMemoryTransport(server), mode=\"auto\") as client:\n print(\"negotiated:\", client.protocol_version)\n result = await client.list_tools()\n print(\"tools the client kept:\", [t.name for t in result.tools])\n\nanyio.run(main)\n```\n\nOutput on `mcp` 2.1.1:\n\n```\nWARNING dropping tool 'bad': invalid x-mcp-header (property 'tags':\n x-mcp-header is only permitted on integer/string/boolean\n properties (got 'array'))\nnegotiated: 2026-07-28\ntools the client kept: []\n```\n\nRegistration succeeded, startup succeeded, `tools/list` served it. The client — correctly, per the client-side MUST — drops it. So the failure mode is **a tool that exists on the server and is invisible to every client**, with the only diagnostic emitted in the client's process, which in a real deployment belongs to someone else.\n\nThe validator that would catch this already exists and is already imported by the server package's transport: `find_invalid_x_mcp_header` in `mcp/shared/inbound.py`. It is simply never run against a tool the server itself is registering.\n\n### Suggested fixes\n\n1. **Run `find_invalid_x_mcp_header` at tool-registration time** and raise. This is the one that matters: it turns a silent cross-process failure into an error at the line that caused it, and it reuses code that is already there.\n2. **A first-class declaration API**, so the extension keyword does not have to be spelled by hand — whatever shape fits the SDK's conventions, e.g. `Annotated[str, McpHeader(\"Region\")]`.\n\nHappy to open a PR for (1) if the direction is agreeable.\n\n### Environment\n\n- `mcp` 2.1.1, `mcp-types` 2.1.1, Python 3.12.9\n- Both reproductions negotiate `2026-07-28`\n","author":{"url":"https://github.com/atsuki-shirasawa","@type":"Person","name":"atsuki-shirasawa"},"datePublished":"2026-09-09T01:28:35Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3484"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:6d7a795a-123d-5e78-36d1-a98632c1beff |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D55E:3A73AA:88CF39:ACAAF8:6B01218D |
| html-safe-nonce | 1d4fdd1528b75825e22716bb4fc8c2c61713dec6a9def56547f851856c97ad4d |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENTVFOjNBNzNBQTo4OENGMzk6QUNBQUY4OjZCMDEyMThEIiwidmlzaXRvcl9pZCI6IjM3NTk4NzQyNTc0NDI2NDQzNjUiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 74badbf27748e435e34f199914375f519043b00cf93edd15d8dc430878660b4a |
| hovercard-subject-tag | issue:5393775805 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3484/issue_layout |
| twitter:image | https://opengraph.githubassets.com/ba9528d48ee9fe019a3280d63a3f40d1d52d8af548ca95009cc08f426fde4ec9/modelcontextprotocol/python-sdk/issues/3484 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/ba9528d48ee9fe019a3280d63a3f40d1d52d8af548ca95009cc08f426fde4ec9/modelcontextprotocol/python-sdk/issues/3484 |
| og:image:alt | Summary MCPServer offers no way to mark a tool parameter with x-mcp-header, and does not validate the annotation when one is smuggled in through pydantic. A server author who gets it wrong gets no ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | atsuki-shirasawa |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width