Implement SEP-2243: HTTP Standardization

[felixweinberger]

This is a tracking issue for implementation of SEP-2243.

[mattzcarey]

Status — SEP-2243 (HTTP Standardization)

Track: B — header machinery starts now; full enforcement waits on Track A's version-gate / envelope.
Spec: seps/2243-http-standardization.md · merged + Final

What's done

• Nothing in main. Client transport does not emit Mcp-Method / Mcp-Name yet — reported by user-issue fix: Send required Mcp-Method/Mcp-Name headers per SEP-2243 #2176 (caomengxuan666, 2026-05-XX) with quoted spec MUSTs.
• Closed exploration: feat(client,server): Mcp-Method/Mcp-Name request headers (SEP-2243) #2069 — Mcp-Method / Mcp-Name set on client POST + validated on server (HeaderMismatchError). Sat on the v2 r3-handlehttp branch.

Open community PRs to consider for the quick fix

• fix(client): send MCP standard POST headers #2178 (fix(client): send MCP standard POST headers, by @he-yufeng) — fixes fix: Send required Mcp-Method/Mcp-Name headers per SEP-2243 #2176; minimal client-only patch for Mcp-Method + Mcp-Name on non-batch requests. Low-risk merge candidate to get the client-side wire-correctness in main now, ahead of the full v2 stack.

Outstanding (acceptance criteria, summary)

• Required headers on every POST: Mcp-Method (always); Mcp-Name (for tools/call, resources/read, prompts/get)
• Header names compared case-insensitively; header values are case-sensitive (e.g. Mcp-Method: TOOLS/CALL → reject)
• Header MUST match body method/name; mismatch → HTTP 400 + JSON-RPC -32001 (HeaderMismatch)
• x-mcp-header tool-annotation: non-empty ASCII, no space or :, primitive-only, case-insensitive-unique → invalid tools excluded from tools/list with a logged warning
• Client stamps Mcp-Param-{Name} headers from tool params; null/absent → omit header
• Non-ASCII / control / leading-or-trailing-whitespace values must be Base64-wrapped: =?base64?<value>?= (wrapper prefix is case-insensitive)
• Type coercion: number → decimal string, boolean → lowercase true/false
• Server-side: header without matching body param → 400 + -32001; invalid base64 padding/chars → 400 + -32001; extra leading/trailing whitespace tolerated; servers/intermediaries MUST decode base64 before comparison
• Security guidance: intermediaries MUST NOT trust Mcp-Param-* for authorization decisions; tool authors SHOULD NOT mark sensitive params with x-mcp-header; intermediaries that don't recognize a header MUST forward it unchanged

Post-85ec3771 clarifications to fold in

• spec#2772 (open) — x-mcp-header clarifications

Suggested phasing (matches the track plan)

1. Now: merge fix(client): send MCP standard POST headers #2178 (or close it in favor of feat(client,server): Mcp-Method/Mcp-Name request headers (SEP-2243) #2069 against v2 stack) — get client header emission right immediately.
2. Now: build the x-mcp-header encoding + decoding library (no transport seam needed yet).
3. After Track A envelope lands: server-side header-vs-body validation + -32001 HeaderMismatch path.

Test backlog

• The 25 R-2243-* rows in the spec page give a 1:1 conformance test list.