Skip to content

[Docs][Server] Document and test that initialize negotiates from th… - #739

Merged
chr-hertel merged 2 commits into
modelcontextprotocol:mainfrom
nbullorini:docs-initialize-protocol-version-header
Nov 16, 2026
Merged

chr-hertel merged 2 commits into
modelcontextprotocol:mainfrom
nbullorini:docs-initialize-protocol-version-header

Conversation

@nbullorini

Copy link
Copy Markdown
Contributor

On initialize the body is authoritative: the MCP-Protocol-Version header plays no part in negotiation and is not compared with params.protocolVersion. This corrects the "Protocol Version Validation" section in docs/run/http.md and adds transport tests for both mismatch directions and a missing header, with and without sessions.

Closes #309

Motivation and Context

As agreed in #309: the docs said the header check happens after the handshake, and nothing pinned down that the header has no effect on initialize, so it could quietly regress to the originally reported behaviour.

How Has This Been Tested?

New transport-level test in StreamableHttpTransportTest covering an older header, a newer header and no header, each with and without sessions, asserting the negotiated version in both the response and the stored session.

Breaking Changes

None. No runtime behaviour changes.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

The ProtocolVersionMiddleware docblock repeated the same inaccurate claim that initialize doesn't carry the header, so it's corrected too.

…e body, not the version header

The MCP-Protocol-Version header sent with `initialize` plays no part in
negotiation and is not compared with `params.protocolVersion`.

Closes modelcontextprotocol#309

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the documentation and regression-coverage changes for initialization version negotiation.

No open issues 🎉

What changed in this PR

Documents and adds regression coverage for body-driven initialize version negotiation, addressing issue #309 without changing runtime behavior.

Changes:

  • Clarifies that the header does not participate in handshake negotiation, while separate header validation still applies.
  • Tests older, newer, and missing headers with and without sessions, checking the response and stored session version.
  • Corrects the middleware docblock to say clients may omit the header on initialize.
File Description
tests/​Unit/​Server/​Transport/​StreamableHttpTransportTest.php Adds six negotiation cases and an initialization request helper.
src/​Server/​Transport/​Http/​Middleware/​ProtocolVersionMiddleware.php Corrects the comment about optional initialization headers.
docs/​run/​http.md Explains body-driven negotiation, version pinning, and modern-header rejection.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the documentation and regression-test updates clarifying body-based initialization-version negotiation.

No open issues 🎉

Review effort: Balanced

@chr-hertel chr-hertel left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @nbullorini - made some minor stylistic abjustments in 36a8eb6 before merging.

@chr-hertel
chr-hertel merged commit 3d2e831 into modelcontextprotocol:main Nov 16, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Streamable HTTP server does not validate body/header protocol-version consistency on initialize

3 participants