feat: implement MCP-Protocol-Version header requirement for HTTP transport by ochafik · Pull Request #614 · modelcontextprotocol/typescript-sdk

ochafik · 2025-06-11T16:57:30Z

Implement MCP-Protocol-Version header requirement for HTTP transport (closes #604)

Motivation and Context

This PR implements the MCP-Protocol-Version header requirement as specified in:

(see similar update in Python SDK: modelcontextprotocol/python-sdk#898)

Clients extract and store the negotiated protocol version from the initialization response, include the MCP-Protocol-Version header in all subsequent HTTP requests after initialization.

Servers validate the presence and correctness of this header for non-initialization requests, returning 400 Bad Request for missing or invalid protocol version headers.

How Has This Been Tested?

Updated all existing tests to include the MCP-Protocol-Version header. Added new tests for header validation.

Breaking Changes

This is a breaking change that requires both clients and servers to be updated. Clients that don't send the MCP-Protocol-Version header will be stuck at the protocol version 2025-03-26.

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

Implementation Details

The implementation adds protocol version tracking to all HTTP-based transports:

Client-side changes:
- Added protocolVersion?: string property to the Transport interface
- Client stores the negotiated protocol version from the initialization response
- HTTP transports (SSE and Streamable HTTP) include the Mcp-Protocol-Version header in all requests after initialization
- The header value matches the negotiated protocol version from the init response
Server-side changes:
- Server sets transport.protocolVersion after successful initialization
- Streamable HTTP server validates the Mcp-Protocol-Version header on all non-initialization requests
- Returns 400 Bad Request for unsupported protocol versions
- Logs a warning if the header version differs from the negotiated version (but still accepts the request if the version is supported)
Key behaviors:
- The header is optional during initialization but required for all subsequent requests
- If a client sends a different but supported protocol version, the server logs a warning but processes the request
- This ensures clients properly track and use the negotiated protocol version throughout the session

… it doesn't match negotiated version (it SHOULD match)

felixweinberger

LGTM barring one loose equality check! Otherwise only nits :)

felixweinberger · 2025-06-12T12:04:33Z

+      // Note: this._requestInit?.headers already set in _commonHeaders
+      // const headers = new Headers({ ...commonHeaders, ...this._requestInit?.headers });


nit: personally don't think this comment adds much value and just adds potential stuff that becomes outdated over time, so would propose just removing the comments

that this._requestInit?.headers is already set in _commonHeaders is imo sufficiently clear from its implementation

felixweinberger · 2025-06-12T12:13:05Z

+  private validateProtocolVersion(req: IncomingMessage, res: ServerResponse): boolean {
+    let protocolVersion = req.headers["mcp-protocol-version"];
+    if (Array.isArray(protocolVersion)) {
+      protocolVersion = protocolVersion[protocolVersion.length - 1];


should we make sure protocolVersion.length > 0? not sure if req.headers would ever return an empty array

I was implicitly relying on the fact that [][-1] === undefined tbh, but yes in practice if a header isn't set we get undefined, if it's set once we get a string, and if set mode than once we get an array of the values.

ah TIL that returns undefined and not an error!

ihrpr

Thank you for working on this!

In general looks good, left some comments to make it consistent with the spec and some small fixes suggestions

ihrpr · 2025-06-12T12:02:53Z

+    if (Array.isArray(protocolVersion)) {
+      protocolVersion = protocolVersion[protocolVersion.length - 1];
+    }


would this ever be true?

Type-wise it's a possiblity (happens if the client sets the header twice, which is legal; I'd rather not explode when that's the case)

ihrpr · 2025-06-12T12:33:43Z

      this._serverCapabilities = result.capabilities;
      this._serverVersion = result.serverInfo;
+      // HTTP transports must set the protocol version in each header after initialization.
+      transport.protocolVersion = result.protocolVersion;


I would prefer not to set the property directly, instead, expose setProtocolVersion

Added setProtocolVersion (optional to avoid having to implement it in all transports - incl. test transports)

…ntextprotocol/typescript-sdk into ochafik/protocol-version

ihrpr

Thank you! 🚀

Set Mcp-Protocol-Version in client requests after init, and warn when…

84971c8

… it doesn't match negotiated version (it SHOULD match)

ochafik requested a review from felixweinberger June 11, 2025 16:57

ochafik marked this pull request as ready for review June 11, 2025 17:53

Merge branch 'main' into ochafik/protocol-version

18f8b40

ochafik mentioned this pull request Jun 11, 2025

require negotiated version when using HTTP #604

Closed

felixweinberger reviewed Jun 12, 2025

View reviewed changes

ihrpr requested changes Jun 12, 2025

View reviewed changes

ochafik added 6 commits June 12, 2025 18:42

add supported versions to error message

bb0592b

use const in test

a28e25a

nits: remove dead comment & align test style on local idioms

e573a0f

Merge branch 'ochafik/protocol-version' of https://github.com/modelco…

4e9d6a7

…ntextprotocol/typescript-sdk into ochafik/protocol-version

remove protocol version mismatch warning

4aaa26d

switch to optional Transport.setProtocolVersion

33257f1

ochafik requested a review from ihrpr June 13, 2025 17:27

ihrpr approved these changes Jun 13, 2025

View reviewed changes

ihrpr merged commit 6b3d326 into main Jun 13, 2025
5 checks passed

ihrpr deleted the ochafik/protocol-version branch June 13, 2025 17:31

		// Note: this._requestInit?.headers already set in _commonHeaders
		// const headers = new Headers({ ...commonHeaders, ...this._requestInit?.headers });

Conversation

ochafik commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Implementation Details

Uh oh!

felixweinberger left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ochafik commented Jun 11, 2025 •

edited

Loading

felixweinberger left a comment •

edited

Loading