Skip to content

SEP-1309: Specification Version Management #1309

Closed as duplicate
Closed as duplicate

Description

@pantanurag555

Preamble

Title: Specification Version Management
Authors: 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.
The intention of allowing SDK releases to offer partial support for a specification version is that the SDK consumers will have the choice to opt in to the available partial features, even if they are still unstable. By default, the SDK should maintain stability guarantees for a 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 tag 2025-03-26 on branch 2.4
  • Specification version 2025-06-18 → SDK version tag 2025-06-18 on branch 3.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

Activity

  1. changed the title [-]SEP: Specification Version Management in MCP[/-] [+]SEP: Specification Version Management using Semantic Versioning[/+] on Aug 6, 2025
  2. changed the title [-]SEP: Specification Version Management using Semantic Versioning[/-] [+]SEP-1309: Specification Version Management using Semantic Versioning[/+] on Aug 8, 2025
  3. 000-000-000-000-000 commented on Aug 16, 2025

    @000-000-000-000-000
    Contributor

    Major Version Changes (X.0.0)

    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.

    Each SDK version release would contain, as part of its code, the specification versions that are supported by the SDK version release.

    Will there be a standard for how SDKs declare this?

    Specification maintainers should create language-agnostic conformance tests for each release to allow SDK maintainers to validate the SDKs behavior against the required feature-set and to act as an additional check for specification maintainers to validate that the changes scheduled for minor releases do not introduce a backward-incompatible behavior.. The exact specifics of the conformance tests are intentionally left out of scope for this SEP.

    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.

    Switching to semantic versioning makes it easier to develop language-agnostic conformance tests for each specification version release.

    When updating the table of support folks should show passing conformance tests for the updated version(s).

    Extendable to Per-Capability Versioning and Negotiation

    This section does not make it clear why this change is compatible with per-capability versioning. Let's make that more explicit.

    Due to the early stage of the specification, SDKs have missed implementing certain features that were later removed from the protocol. For example, the batching feature was never implemented in the Java SDK before being removed from the specification. Rather than requiring maintainers to backfill these historical gaps, starting fresh with version 1.0.0 after this specification is accepted provides a clean baseline where all SDKs can achieve consistent feature parity moving forward.

    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?

  4. LucaButBoring commented on Aug 18, 2025

    @LucaButBoring
    Contributor

    Do we understand what is taking the SDKs so long today to get to compliance?

    This comes down to a few things, I believe (speaking mostly from the perspective of Java):

    1. Lack of compatibility tests: Without a test suite to build against, maintainers are left to itemize the required changes themselves and get bugged by users if they miss something (sometimes months down the line). This SEP would be a step towards remediating that, as noted in the section on conformance testing.
    2. Lack of maintainer bandwidth: This is fairly self-explanatory, and we've experienced this already on the Java SDK.
    3. Protocol features not quite meshing with existing implementations: Think of cases like implementing unions in Java, or building APIs for cancellation notifications that work with how the Java sync client is currently built, etc.

    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.

  5. pantanurag555 commented on Aug 18, 2025

    @pantanurag555
    Author

    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.

    I agree. Added a line to indicate these are examples and not all-encompassing guidelines.

    Will there be a standard for how SDKs declare this?

    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.

    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.

    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

    When updating the table of support folks should show passing conformance tests for the updated version(s).

    Agreed. Added to the list of rationale points.

    This section does not make it clear why this change is compatible with per-capability versioning. Let's make that more explicit.

    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.

    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?

    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. 6 remaining items

  7. pantanurag555 commented on Oct 16, 2025

    @pantanurag555
    Author

    @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.

  8. moved this from Review Batch to Accepted in SEP Review Pipelineon Nov 6, 2025
  9. moved this from Backlog to In review in 2025-11-25 Implementationon Nov 6, 2025
  10. removed
    draftSEP proposal with a sponsor.
    on Nov 6, 2025
  11. pantanurag555 commented on Nov 9, 2025

    @pantanurag555
    Author

    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.

  12. dsp-ant commented on Nov 11, 2025

    @dsp-ant
    Member

    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.

  13. 000-000-000-000-000 commented on Nov 19, 2025

    @000-000-000-000-000
    Contributor

    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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions