# 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. Last verified against MCP specification 2026-07-28: Tools on 2026-11-18.

## 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#x-mcp-header)

## 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:

```json
"amount": { "type": "number", "x-mcp-header": "Amount" }
```

After:

```json
"region": { "type": "string", "x-mcp-header": "Region" }
```

### TypeScript SDK

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-x-mcp-header-sensitive)
- [Tool fields have the types the schema defines](https://isokron.ai/mcp-check/checks/spec-field-types)
- [The tools/list result carries ttlMs and cacheScope](https://isokron.ai/mcp-check/checks/spec-envelope-cache)
- [MCP specification 2026-07-28: tools/list rules](https://isokron.ai/mcp-check/checks/protocol)

## Further reading

- [Shipping a production MCP server on the 2026-07-28 spec](https://isokron.ai/research/production-mcp-server)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
