Skip to content

fix: add backward compatibility for MCP servers returning older protocol versions #444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Conversation

tzolov
Copy link
Contributor

@tzolov tzolov commented Aug 4, 2025

  • Add ProtocolVersions interface with version constants
  • Change protocolVersion() to protocolVersions() returning List
  • Streamable HTTP clients now support both 2024-11-05 and 2025-03-26
  • Fixes compatibility with MCP servers that return 2024-11-05 instead of 2025-03-26

Resolves #436
Related to #438

Add multi-protocol version support to fix MCP server compatibility issues

Motivation and Context

Some MCP server implementations that support the newer "2025-03-26" protocol version incorrectly return "2024-11-05" during initialization instead. This causes compatibility issues where streamable HTTP clients (which support 2025-03-26) cannot connect to these servers because they don't advertise support for the older protocol version.

This change refactors the protocol version handling to support multiple versions simultaneously, allowing streamable HTTP transports to advertise compatibility with both "2024-11-05" and "2025-03-26" protocol versions, ensuring broader server compatibility.

How Has This Been Tested?

  • All existing unit and integration tests have been updated and pass
  • Tested compatibility with MCP servers that return different protocol versions
  • Verified that streamable HTTP clients can now connect to servers returning either protocol version
  • SSE transports continue to work with their respective protocol versions

Breaking Changes

Yes, this introduces breaking changes to the transport API:

  • protocolVersion() method has been replaced with protocolVersions() returning List<String>
  • All transport implementations now need to return a list of supported protocol versions
  • Custom transport implementations will need to be updated to use the new API

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

  • Added ProtocolVersions interface to centralize protocol version constants and avoid hardcoded strings
  • Streamable HTTP transports now support both MCP_2024_11_05 and MCP_2025_03_26 for maximum compatibility
  • SSE transports continue to support only their respective protocol versions as they are transport-specific
  • Updated error messages in LifecycleInitializer to include more detailed exception information
  • All test cases have been updated to work with the new multi-version API
  • The change maintains backward compatibility at the protocol level while updating the Java API

…col versions

- Add ProtocolVersions interface with version constants
- Change protocolVersion() to protocolVersions() returning List<String>
- Streamable HTTP clients now support both 2024-11-05 and 2025-03-26
- Fixes compatibility with MCP servers that return 2024-11-05 instead of 2025-03-26

Resolves modelcontextprotocol#436
Related to modelcontextprotocol#438

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov tzolov merged commit 5e035ea into modelcontextprotocol:main Aug 4, 2025
1 check 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.

Unsupported protocol version from the server: 2024-11-05
1 participant