x-mcp-header values follow the rules
x-mcp-header (MCP 2026-07-28) mirrors an argument into an HTTP header; its value must be a non-empty RFC 9110 token, unique ignoring case, on a string, integer or boolean property directly under "properties", or HTTP clients drop the tool.
Check spec-x-mcp-header · MCP specification 2026-07-28 · default severity: blocking · rubric 2.1.0
What fails
A tool with an invalid x-mcp-header is left out of tools/list by every conforming HTTP client, with at most a log line, so the tool silently disappears. Values must be non-empty RFC 9110 tokens, unique ignoring case, on string, integer or boolean properties (not number) reached from the root through "properties" only.
The rule
Clients using the Streamable HTTP transport MUST reject tool definitions where any
x-mcp-headervalue violates these constraints.
How to fix it
Fix the value named in the message: use a token such as "Region", put it on a string, integer or boolean property directly under "properties", and give each header a different name.
- Use a token such as "Region" (letters, digits and !#$%&'*+-.^_`|~ only).
- Put it on a string, integer or boolean property reached from the root through "properties" only (not number, not inside arrays).
- Give each header a different name, ignoring case.
"amount": { "type": "number", "x-mcp-header": "Amount" }"region": { "type": "string", "x-mcp-header": "Region" }TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'list_buckets',
{
title: 'List buckets',
description: 'List storage buckets in one region. Use when the user asks what storage exists.',
inputSchema: z.strictObject({
region: z.string().meta({'x-mcp-header':"Region"}).describe('Region code, for example eu-west-1'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ region }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="List buckets",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def list_buckets(
region: Annotated[str, Field(description="Region code, for example eu-west-1", json_schema_extra={"x-mcp-header": "Region"})],
) -> str:
"""List storage buckets in one region. Use when the user asks what storage exists."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
What is x-mcp-header for?
It lets an HTTP intermediary (load balancer, gateway) route on an argument without parsing the JSON-RPC body, by copying the value into a request header.
Why does the tool disappear instead of failing?
The specification says Streamable HTTP clients MUST reject tool definitions with invalid x-mcp-header values, and most do it by leaving the tool out, at most with a log line.
Related checks
- No x-mcp-header on secrets or personal data
- Tool fields have the types the schema defines
- The tools/list result carries ttlMs and cacheScope
- All checks in MCP specification 2026-07-28: tools/list rules
Further reading
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere