Document initialize body protocolVersion is authoritative on Streamable HTTP#352
Open
koic wants to merge 1 commit into
Open
Conversation
…amable HTTP ## Motivation and Context When an `initialize` POST carries an `MCP-Protocol-Version` HTTP header that disagrees with `params.protocolVersion` in the JSON-RPC body, the Streamable HTTP server accepts the request and negotiates using the body value. The behavior was already encoded in `handle_post` (the header check is skipped on `initialize`) but it was not stated in the code and there was no regression test for the specific mismatch case. MCP 2025-06-18 / 2025-11-25 only requires `MCP-Protocol-Version` on requests subsequent to `initialize`, and the spec does not require the header and body to agree on the initial `initialize`. All official MCP SDKs (TypeScript, Python, Rust, Java, Go, PHP) accept the mismatch and treat the JSON-RPC body as authoritative. ## How Has This Been Tested? Streamable HTTP tests: two new regression tests confirm that on an `initialize` POST with a supported but mismatched `MCP-Protocol-Version` header, the server returns HTTP 200 and the response's `result.protocolVersion` matches the JSON-RPC body value, in both mismatch directions (header older / body newer, and header newer / body older). ## Breaking Changes None. The behavior is unchanged: `initialize` requests with a mismatched `MCP-Protocol-Version` header are still accepted, and the JSON-RPC body `params.protocolVersion` continues to drive negotiation. This commit only adds an explanatory comment and regression tests. Closes modelcontextprotocol#351.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Context
When an
initializePOST carries anMCP-Protocol-VersionHTTP header that disagrees withparams.protocolVersionin the JSON-RPC body, the Streamable HTTP server accepts the request and negotiates using the body value. The behavior was already encoded inhandle_post(the header check is skipped oninitialize) but it was not stated in the code and there was no regression test for the specific mismatch case.MCP 2025-06-18 / 2025-11-25 only requires
MCP-Protocol-Versionon requests subsequent toinitialize, and the spec does not require the header and body to agree on the initialinitialize. All official MCP SDKs (TypeScript, Python, Rust, Java, Go, PHP) accept the mismatch and treat the JSON-RPC body as authoritative.How Has This Been Tested?
Streamable HTTP tests: two new regression tests confirm that on an
initializePOST with a supported but mismatchedMCP-Protocol-Versionheader, the server returns HTTP 200 and the response'sresult.protocolVersionmatches the JSON-RPC body value, in both mismatch directions (header older / body newer, and header newer / body older).Breaking Changes
None. The behavior is unchanged:
initializerequests with a mismatchedMCP-Protocol-Versionheader are still accepted, and the JSON-RPC bodyparams.protocolVersioncontinues to drive negotiation. This commit only adds an explanatory comment and regression tests.Closes #351.
Types of changes
Checklist