2026-07-28 lets an HTTP gateway route requests using headers before it reads a JSON-RPC body. This applies to the Host’s connection to an MCP server, including requests for MCP App tools and ui:// resources. The View-to-Host ui/initialize exchange uses postMessage, so these HTTP headers do not apply to it.
sunpeak’s public HTTP server wrappers currently use the legacy
2025-11-25 transport. The
headers on this page describe a server and client using core MCP 2026-07-28; setting
--stateless does not switch sunpeak’s wire protocol. See MCP 2026-07-28 for MCP
Apps for the compatibility boundary.Map requests to headers
For each modern Streamable HTTP JSON-RPC request POST, the client sendsMCP-Protocol-Version and Mcp-Method alongside the body. The version must match _meta["io.modelcontextprotocol/protocolVersion"], and the method must match the body method. Some methods also require Mcp-Name:
For example, reading an MCP App resource with
params.uri: "ui://orders/view.html" sends Mcp-Method: resources/read and Mcp-Name: ui://orders/view.html. A gateway can route the resource request by URI without parsing JSON.
Route on a tool argument with x-mcp-header
A tool can annotate a scalar property in its inputSchema so a modern HTTP client copies that argument into a Mcp-Param-* header. This example makes region available to a gateway:
Use this only for routing data that an intermediary may see. Do not annotate passwords, API keys, access tokens, or personal data.
params.name: "show_orders" and params.arguments.region: "us-east", the client sends:
region argument. The header is a copy for routing, not a replacement for server-side input validation. If the argument is absent or null, the client omits its parameter header.
An annotated property must have type string, integer, or boolean. Its header suffix must be a valid HTTP field-name token and unique without regard to case. Clients encode integers in decimal and booleans as true or false. A string that cannot be sent as plain ASCII, including one with leading or trailing whitespace or one that matches the encoding marker, uses =?base64?BASE64?= encoding. The same rule applies to Mcp-Name values, including ui:// resource URIs; the server decodes encoded headers before comparing them with the body. The annotation can appear within nested object properties, but not inside an array, schema composition, or $ref. TypeScript SDK users should use z.int() for an annotated integer; z.number() describes a JSON Schema number and is invalid here.
Check the header against the body
The server checks the version, method, name, and annotated argument headers against the JSON-RPC body. A missing required header or a mismatch returns HTTP 400 with JSON-RPC error code-32020 (HeaderMismatch). Gateways that rely on mirrored headers should first verify that the request uses the modern protocol version; a legacy client does not provide the same header guarantees.
See the MCP Streamable HTTP transport specification for the complete wire rules and MCP Apps capability detection for the separate View metadata.