Skip to content
IsoKron

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-header value violates these constraints.

Source: MCP specification 2026-07-28: Tools

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.

  1. Use a token such as "Region" (letters, digits and !#$%&'*+-.^_`|~ only).
  2. Put it on a string, integer or boolean property reached from the root through "properties" only (not number, not inside arrays).
  3. Give each header a different name, ignoring case.
Before
"amount": { "type": "number", "x-mcp-header": "Amount" }
After
"region": { "type": "string", "x-mcp-header": "Region" }

TypeScript SDK

TypeScript
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

Python
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.

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