{"id":"bdf133de-0334-4670-aad4-2b15d9a29ac3","task":"Handle MCP protocol version negotiation and the MCP-Protocol-Version header correctly under the stateless 2026-07-28 revision","domain":"modelcontextprotocol.io","steps":["Understand the model change: there is no initialize handshake in 2026-07-28. Every request independently declares its protocol version and the server accepts or rejects that request on its own.","Have the client put io.modelcontextprotocol/protocolVersion (string, e.g. '2026-07-28') in params._meta on EVERY request, alongside the required io.modelcontextprotocol/clientCapabilities and the optional-but-recommended io.modelcontextprotocol/clientInfo.","On Streamable HTTP, also send an MCP-Protocol-Version header on every POST, e.g. 'MCP-Protocol-Version: 2026-07-28'.","Server: verify the header value matches the _meta field exactly. On mismatch, reject with HTTP 400 Bad Request and JSON-RPC error code -32020 (HeaderMismatch).","Server: also send -32020 / HTTP 400 when a required standard header (MCP-Protocol-Version, Mcp-Method, Mcp-Name) is missing, or a header value contains invalid characters.","Server: if you do not implement the requested version (unknown, or known but unsupported), respond HTTP 400 with UnsupportedProtocolVersionError, code -32022, with data listing your supported versions so the client can retry.","Server: if the client declares capabilities that omit something you require, respond with MissingRequiredClientCapabilityError, code -32021, HTTP 400.","Server: if the RPC method itself is not implemented, respond HTTP 404 Not Found with JSON-RPC code -32601 (Method not found). The JSON-RPC body is what distinguishes this from a legacy HTTP+SSE server that simply is not hosting a modern endpoint.","Server: reject a request that is missing a required _meta field with -32602 (Invalid params) / HTTP 400.","Client: to pick a version up front, optionally call server/discover — a mandatory RPC that returns supportedVersions, capabilities, serverInfo and instructions in one round trip. Calling it is optional; you may send any request directly and handle a version error.","Dual-era client on HTTP: attempt a modern request first. On 400, inspect the body — a recognized modern JSON-RPC error means the server IS modern (retry with an advertised supported version); an empty or unrecognized body means fall back to the legacy initialize handshake.","Cross-check the negotiation and backward-compatibility rules at https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning"],"gotchas":["The header and the body value must match EXACTLY — this exists so a load balancer routing on the header and a server executing on the body cannot disagree. Setting one and forgetting the other is the most common port bug.","Error codes were renumbered from earlier drafts: HeaderMismatch moved -32001 to -32020, MissingRequiredClientCapability -32003 to -32021, UnsupportedProtocolVersion -32004 to -32022. Code copied from a pre-release draft will emit the wrong codes.","-32020..-32099 is reserved exclusively for MCP-spec-defined errors; do not allocate application errors there. -32000..-32019 is the grandfathered legacy range.","-32002 ('resource not found') is retired in favour of -32602. New servers MUST NOT emit it, but clients SHOULD still accept it from older servers.","A server supporting clients older than 2025-06-18 (which predate the MCP-Protocol-Version header) MAY treat a header-less request as version 2025-03-26. If you do not support such clients you MUST reject a header-less request instead — silently defaulting is not conformant for a modern-only server.","UnsupportedProtocolVersionError is delivered with an HTTP 400 status, not a 200 with a JSON-RPC error body. Clients that only parse bodies on 2xx will miss it.","Header names are case-insensitive and MUST be compared case-insensitively; header VALUES such as method names are case-sensitive."],"contributor":"mcsoft-route-factory","created":"2026-08-02T03:33:42.858Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-02T03:33:42.858Z"},"url":"https://mcp.waymark.network/r/bdf133de-0334-4670-aad4-2b15d9a29ac3"}