Skip to content

Require protocol_version to be a string#2763

Merged
maxisbey merged 1 commit into
mainfrom
protocol-version-str
Jun 2, 2026
Merged

Require protocol_version to be a string#2763
maxisbey merged 1 commit into
mainfrom
protocol-version-str

Conversation

@maxisbey
Copy link
Copy Markdown
Contributor

@maxisbey maxisbey commented Jun 2, 2026

InitializeRequestParams.protocol_version and InitializeResult.protocol_version were typed str | int; this narrows both to str, and drops a now-redundant str(...) coercion in the streamable HTTP client transport.

Motivation and Context

The spec schema defines protocolVersion as a plain string. The int variant dates back to the pre-release protocol, where the handshake used the literal integer 1 — when versioning moved to date strings in 2024-10-07, the union was kept so old peers wouldn't fail validation. The TypeScript SDK removed its equivalent (z.string().or(z.number().int())z.string()) in November 2024 (modelcontextprotocol/typescript-sdk@0bf7e66); the Python SDK never followed.

The int arm is dead in practice: an integer version can never match SUPPORTED_PROTOCOL_VERSIONS (a list[str]), so on the server it always fell into the version-mismatch fallback, and on the client it always raised RuntimeError. Accepting integers only changed the failure mode for peers that haven't been able to negotiate since 2024.

How Has This Been Tested?

Full test suite passes locally with 100% coverage (./scripts/test). No tests exercised integer versions.

Breaking Changes

Peers that send an integer protocolVersion now get a validation error instead of a version-mismatch response; they could not complete negotiation before either. Type annotations referencing the union (str | int) on these fields will need updating.

Types of changes

  • Breaking change (fix or feature that would cause existing functionality to change)

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 field's pre-history in this repo: protocolVersion: Literal[1]str | int in 2d55eab ("Update types for protocol version 2024-10-07").

The MCP schema defines protocolVersion as a plain string. The int variant
only existed for compatibility with pre-release protocol negotiation
(before 2024-10-07 date-based versioning), which sent protocolVersion: 1.
Integer versions can never successfully negotiate against the supported
version list, so accepting them only changed the failure mode. This
matches the TypeScript SDK, which made the same change in November 2024.
@maxisbey maxisbey marked this pull request as ready for review June 2, 2026 16:27
@maxisbey maxisbey merged commit c91f406 into main Jun 2, 2026
32 checks passed
@maxisbey maxisbey deleted the protocol-version-str branch June 2, 2026 16:27
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.

2 participants