Repository navigation
Closed as duplicate
Labels
Milestone
Description
Preamble
Title: Specification Version ManagementAuthors: Anurag Pant, Surbhi Bansal
Status: Accepted with Changes
Type: Standards Track
Created: 08/06/2025
Abstract
This SEP provides clear guidelines that enable SDK maintainers to independently manage their releases while maintaining transparent specification compliance. The recommended framework aims to improve SDK discoverability for end users, ensure reliable official SDK interoperability and allow SDK maintainers to evolve their implementations at their own pace while clearly communicating specification support levels.Motivation
The existing protocol specification is inadequate because it lacks guidance around SDK version management that can help standardize the process around official SDK releases and help improve SDK interoperability. As MCP moves towards supporting remotely hosted MCP servers, there need to be some guidelines around how SDK owners can announce specification version compliance to the end users. The guidelines should also leave room to allow an SDK to release patches or to make breaking changes that may or may not be related to the features in the specification version.- Guidelines will standardize how end users discover different specification version compliant SDK versions
- Discovery will allow for end-users to reliably establish connection with a remote client/server written in another MCP SDK which is compliant with the same specification version
- MCP SDK maintainers will be able to make breaking changes, when necessary to fix the SDK implementation and/or improve developer experience, while versioning the SDK at their own pace
Specification
Specification Version Semantics
MCP specification maintainers will be responsible for releasing new versions.- All versions MUST be accompanied by detailed release notes to alert the SDK maintainers about the changes required to be compliant with a specification version.
SDK Versioning
SDK maintainers should have the freedom to do SDK version releases at their own pace. Each SDK version release would contain, as part of its code, the specification versions that are supported by the SDK version release.- SDK maintainers MUST use version release tags to mark compliance with different specification versions.
- SDK maintainers MUST publish release notes that call out with which specification versions the release is compliant.
- An SDK version release SHOULD implement all features specified in a specification version if it claims compliance with that version, and SHOULD NOT implement features introduced in versions beyond its declared compliance range.
- An SDK version MAY implement partial compliance with a specification version under the following conditions:
- SDK release notes MUST explicitly document which features from the partially supported specification version are implemented.
- The SDK MUST use its latest fully-supported version as the default specification version setting.
- The SDK MUST provide configuration options allowing users to set the maximum specification version used during version negotiation.
- All features from the partially supported specification version MUST be implemented with version-aware behavior that respects the user-configured maximum specification version.
Specification-SDK Version Mapping Strategy
Specification documentation will be used to keep a track of the status of specification releases across all official MCP SDKs. The documentation will contain an implementation tracking matrix. This will aid in SDK version discovery for end-users as well as tracking how far along specification compliance is across the official SDKs.- SDK maintainers MUST update the table whenever they put out a version release that meets the specification compliance
- SDK maintainers MUST update the table whenever they put out a version release that drops support for a prior specification version
- The update to the table MUST only have the minimum and maximum (if support dropped in previous release) SDK version that supports the corresponding specification version.
Implementation Tracking Matrix
| Specification Version | Status | Python SDK | TypeScript SDK | Java SDK |
|---|---|---|---|---|
| 2024-11-05 | ✅ Stable | ✅ 2.0.5 - 2.1.4 | ✅ 1.0.3 - 1.5.0 | ✅ 0.0.3 |
| 2025-03-26 | ✅ Stable | ✅ 2.2.0 | ✅ 1.1.4 - 2.1.0 | ✅ 0.11.0 |
| 2025-06-18 | 🚧 In Progress | 🚧 2.3.0-beta.1 | ✅ 2.2.0 | 🚧 main |
| 2025-09-29 | 📋 Planned | ❌ Not Started | ❌ Not Started | ❌ Not Started |
Rationale
Independent SDK Versioning with Protocol Support Declaration
The decision to allow SDKs to version independently while declaring supported specification versions provides maximum flexibility while maintaining clear compatibility relationships. This approach:- Maximizes SDK maintainer flexibility: Each SDK can release at their own pace without coordination overhead
- Reduces coordination complexity: No need to synchronize releases across multiple repositories
- Enables gradual adoption: SDKs can add support for new specification versions when ready
- Maintains backward compatibility: SDKs can support multiple specification versions simultaneously
Backward Compatibility
This change is completely backwards compatible.Alternatives Considered
Listed below are some alternative approaches that were considered for implementing versioning in MCP SDKs.Specification Version Dictates SDK Release Tags
In this approach, release tags will be tightly coupled with MCP specification versions. Release tags will be used to mark different commits with specification versions. These release tags will signify that at that commit, the SDK code is compliant with the marked specification version. Branches would be tied to SDK implementations. SDKs would be able to use semantically versioned (if the SDK uses semantic versioning) branches to signify minor or breaking SDK changes.Any official SDK would implement specification versions using aligned version tags in the repository:
- Specification version
2025-03-26→ SDK version tag2025-03-26on branch2.4 - Specification version
2025-06-18→ SDK version tag2025-06-18on branch3.1
Drawbacks
- Overly Prescriptive Limits flexibility while complicating release cycles and development process for SDK maintainers
- Package Manager Integration Issues Creates significant problems with external package managers (Cargo, PyPI, NPM) where published releases would either need to correspond to specification or SDK versions. Would allow for breaking changes (either specification or SDK) within the same major version on package managers.
Specification Dictates SDK Implementation Details
This approach dictates the implementation details across the official SDKs. This can be done in a few ways:- Single Repository - Different Folders/Namespaces: All specification versions are maintained within the same repository but in separate folders/namespaces.
- Same Repository - Base Class with Subclasses + Conditional Statements: All specification versions share a common codebase with version-specific behavior implemented through inheritance and polymorphism.
- Different Repositories for Different Versions: Each specification version is maintained in a completely separate repository to create clear boundaries and allow for independent development.
Drawbacks
- Prescribes implementation details that might not be viable across different SDKs
- Introduces significant complexity due to either folder structure, polymorphic behavior, build system management or dependency management
- Leads to code duplication and inability to reuse common code. Increases maintenance overhead.
- Leads to increased storage and infrastructure requirements when trying to support multiple versions
Reacted by Mike McLean, Peder Holdgaard Pedersen, Kurtis Van Gent, Sunish Sheth, Luca Chang, Cliff Hall, Michael Hesler, TerminalMan and bzsurbhi
Reacted by Zachary German, Darshan Murthy, Luca Chang, Nick, Sunish Sheth, Brent Martin Miller, TerminalMan and bzsurbhi
Activity
[-]SEP: Specification Version Management in MCP[/-][+]SEP: Specification Version Management using Semantic Versioning[/+][-]SEP: Specification Version Management using Semantic Versioning[/-][+]SEP-1309: Specification Version Management using Semantic Versioning[/+]000-000-000-000-000 commentedon Aug 16, 2025
I think these sections are meant to provide examples of the things which could be in that release -- let's make it clear these are examples and not all-encompassing.
Will there be a standard for how SDKs declare this?
This is convenient :P - can we open an issue for conformance testing if one does not yet exist? We can upgrade it it a SEP eventually.
When updating the table of support folks should show passing conformance tests for the updated version(s).
This section does not make it clear why this change is compatible with per-capability versioning. Let's make that more explicit.
What does it actually mean to start fresh? Does this just mean that we are not going to force that SDKs eventually implement all features for dated versions, but going forward for semantic versions there will be an expectation for SDKs to get to exact compliance?
Do we understand what is taking the SDKs so long today to get to compliance?
LucaButBoring commentedon Aug 18, 2025
This comes down to a few things, I believe (speaking mostly from the perspective of Java):
2 and 3 are regular development issues we can work to resolve, but 1 is a big one which this SEP will lay groundwork for.
pantanurag555 commentedon Aug 18, 2025
I agree. Added a line to indicate these are examples and not all-encompassing guidelines.
I don't think there needs to a standard way for SDKs to declare this in their release notes. As long as the release notes can clearly indicate the range of semantic versions that SDK release supports, the SDK maintainers should be able to structure the release notes as they deem fit. Open to discussion if you do not agree on this.
I believe it will offer a lot of benefits in ensuring interoperability between different SDKs in the long run. Opened an issue to start a discussion around conformance testing: #1358
Agreed. Added to the list of rationale points.
I have tried to add a little more color to this section. Please take a look and let me know if it addresses the concern.
I don't think SDKs maintainers will realistically backfill for previous dated versions especially since some SDKs might have already missed out on the previous feature sets of the earlier dated versions. Some of the features might not exist in the latest version or have changed considerably since their introduction. This, along with the why the SDKs take so long to get to compliance, can be attributed to the fact that there have been limited open-source contributors and that the protocol along with its official SDKs was in its nascent stage. As the protocols and official SDKs mature (and the community grows), there will be an expectation to have regular releases with the latest complete feature set. Defining these guidelines along with the update to the versioning system would also outline this in the specification. It is still possible the SDKs might not be able to get to the exact compliance for certain future versions due to development issues but this information would be easily observable via the implementation tracking matrix and developers can use that to make a decision about which SDK meets their requirements.
6 remaining items
pantanurag555 commentedon Oct 16, 2025
@dsp-ant Just wanted to check in regarding the next steps. I saw there was some activity on #1444 and #1648 but I am not sure if that is tangential to this SEP, supercedes it or plans to build further on it.
pantanurag555 commentedon Nov 9, 2025
Added some comments to the implementation PR #1404. Please take a look and drop some comments. Hoping to get this merged in the next week so that it is ready for the November release.
dsp-ant commentedon Nov 11, 2025
I think this needs to get a bit more discussion as we have a lot of comments. There might also be come considerations how it fits into the #1730 . Since this is somewhat independent from the MCP data layer spec, it's not urgent to get this in today. We should continue to push on this to give SDK people a chance to implement this.
000-000-000-000-000 commentedon Nov 19, 2025
Hey folks -- quick update on this SEP: we think there is a lot of overlap between this proposal and the proposal for tiering / conformance testing. Given this, we are planning NOT to merge the changes described here in favor of pursuing the approach outlined in 1730. We will do a lightweight update to docs to make it possible for SDK owners to sign-post specific capabilities / version compliance till the point that compliance tests are merged. Thank you all for your comments / contributions to this SEP!