T12 - client HTTP request headers

[kubinio123]

Target branch: 2026-07-28-protocol-support

Requires:

• T10 - client stateless lifecycle #248

Every POST a chimp client sends on the stateless wire carries the request headers the spec requires, including header values derived from tool arguments. The client refuses tool definitions whose header annotations are invalid.

Standard headers

• Every POST carries Mcp-Method equal to the JSON-RPC method, case preserved.
• tools/call and prompts/get POSTs carry Mcp-Name equal to params.name. resources/read POSTs carry Mcp-Name equal to params.uri.
• A value that is not plain ASCII, or that has leading or trailing spaces or control characters, is sent in the Base64 sentinel form defined by the spec.
• Legacy requests are unchanged. stdio has no headers.

Custom headers from tool arguments

• When a tool's input schema marks a property with x-mcp-header, the client mirrors that argument into an Mcp-Param-<name> header on the tools/call POST.
• Values follow the spec encoding: plain ASCII strings as they are, other strings in the Base64 sentinel form, booleans as true or false, numbers as their JSON text. A null argument produces no header. An argument without the annotation produces no header.

Invalid annotations

• When tools/list over HTTP returns a tool whose x-mcp-header value is invalid (empty, not a string, the same header name on two properties, or a name with spaces, colons, non-ASCII or control characters), the client drops that tool from the result and keeps the others, logging a warning.
• Over stdio the annotations are ignored.

Coverage

• The rules above hold for the sync HTTP transport and the streaming HTTP transports on ZIO, Ox and Pekko.
• The conformance client handles http-standard-headers, http-custom-headers (tool arguments come from MCP_CONFORMANCE_CONTEXT) and http-invalid-tool-headers.

Spec:

• Streamable HTTP - Standard Request Headers
• Streamable HTTP - Custom Headers from Tool Parameters
• Streamable HTTP - Value Encoding
• Streamable HTTP - Client Behavior
• Streamable HTTP - Case Sensitivity
• Tools - x-mcp-header

Conformance scenarios that must pass after this task:

• Client: http-standard-headers, http-custom-headers, http-invalid-tool-headers.

Docs: yes.

• docs/client/transport.md: the headers the HTTP transport adds on the stateless wire, x-mcp-header mirroring, and the filtering of tools with invalid annotations.