Use valid HTTP header mappings in Tool input

MCP 2026-07-28 gives x-mcp-header meaning on string, integer, or boolean input properties reachable through properties chains. Check header tokens, placement, and case-insensitive uniqueness. Earlier protocol versions preserve the keyword without applying those MCP header semantics.

Requirement

An x-mcp-header annotation is a non-empty HTTP field-name token on a boolean, integer, or string property reachable from the input schema root through properties only, and is unique case-insensitively within the Tool.

Details

Rule ID: mcp.tool.input-schema.x-mcp-header
Owner: mcp
Surface: Tool · Path: inputSchema properties x-mcp-header
Kind: semantic
Requirement level: Not specified in the rule record
Status: internal · Enforcement: internal

Protocol version applicability

`2024-11-05`	`2025-03-26`	`2025-06-18`	`2025-11-25`	`2026-07-28`
opaque	opaque	opaque	opaque	applies

Required by

MCP Description 0.9.0, Section 9.2
- 9. Tools: req-tool-x-mcp-header

Based on

Tier 1 — MCP schema.ts and normative specification text: MCP 2026-07-28 specification, Streamable HTTP transport, x-mcp-header validity and extraction rules
- https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/tools.mdx#L334-L402
Tier 1 — MCP schema.ts and normative specification text: MCP 2026-07-28 schema.ts, interface Tool, inputSchema doc comment
- validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997

Examples

Valid example

Source: expected-valid/custom-tool-schema-keywords.json · Selected: /tools/0/inputSchema/properties/region

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

Invalid example

Source: expected-invalid/invalid-mcp-header-value.json · Selected: /tools/0/inputSchema/properties/region

{
  "type": "number",
  "x-mcp-header": "Invalid Header"
}

Invalid example

Source: expected-invalid/invalid-mcp-header-placement.json · Selected: /tools/0/inputSchema/allOf/0/properties/region

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

Invalid example

Source: expected-invalid/duplicate-mcp-header.json · Selected: /tools/0/inputSchema/properties/fallbackRegion

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

Rule not applicable

The rule does not run on this fragment for any MCP protocol version it applies to.

Source: expected-valid/protocol-version-inapplicable-mcp-header.json · Selected: /tools/0/inputSchema

{
  "type": "object",
  "properties": {
    "region": {
      "type": "object",
      "x-mcp-header": 7
    },
    "primary": {
      "type": "string",
      "x-mcp-header": "X-Region"
    },
    "fallback": {
      "type": "string",
      "x-mcp-header": "x-region"
    }
  },
  "allOf": [
    {
      "properties": {
        "composed": {
          "type": "array",
          "x-mcp-header": "Invalid Header"
        }
      }
    }
  ]
}

Rule Source Code

tool.yaml at immutable tag v0.9.0-rc.3.