SEP-XXXX: Extension Versioning

[LucaButBoring]

SEP-2133 establishes that extensions evolve independently of the core protocol and SHOULD be versioned, but it leaves the versioning approach unspecified and defers extension dependency declaration to future work. This proposal fills both gaps with a single mechanism. Each extension carries a semantic version in its settings object, and MAY declare the core protocol version its behavior depends on. A difference in the major version means the two peers are incompatible; they negotiate a shared major version through inline retry, as they negotiate a protocol version (see protocol version negotiation). A difference in the minor version is not a conflict: each peer uses the features common to both, and neither rejects the other. A difference in the patch version changes nothing about how the peers interoperate. A new error code, -32005 (Unsupported Extension Version), reports a major-version mismatch and tells the client which major versions the server supports, so it can retry against one of them.

Motivation and Context

SEP-2133 scoped itself narrowly: it defined how extensions are governed, identified, and negotiated, but excluded two compatibility concerns from its scope. Under Not Specified, it omits both extension dependencies on core protocol versions and a concrete versioning approach, recording only that "Extensions SHOULD be versioned, but exact versioning approach is not specified here." Three problems follow from those omissions, and each currently surfaces as a runtime failure rather than a negotiated outcome.

1. An extension's protocol-version dependency is undiscoverable.
2. An extension cannot roll out a breaking change of its own.
3. Optional, non-breaking features cannot be advertised.

This proposal address all three issues by introducing a versioning scheme and negotiation pattern that can generalize across extensions.

Based on #11 from and my previous versioning draft.

How Has This Been Tested?

Hasn't.

Breaking Changes

Technically if extensions are already using version as a settings field, but as far as I've seen they aren't.

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

AI Use Disclosure: Claude wrote this and I made it revise its own work for several hours after I tore it apart.

[pja-ant]

I have to say I did a poor job of writing out how this was all intended to work in SEP-2133, but after reading this I'm still finding myself unconvinced that we need anything new in the protocol to handle the scenarios described in the Motivation section. Here's how I'd expect things to work with how the protocol stands today:

Core protocol version dependencies

The key thing is that the extensions themselves (e.g. Tasks) should just state plainly in their SEP language that they require a specific protocol version. This is no different from e.g. subscriptions/listen requiring 2026-07-28 in the core protocol. We don't need protocol message to say that subscriptions/listen requires 2026-07-28, the client and server SDKs just know it because they implement the extension (or they don't, in which case it just gets rejected anyway, regardless of protocol).

What this means is that a server telling the client that Tasks v1.2.3 requires 2026-07-28 is just redundant. The client already knows this because it implements Tasks and the Tasks extension says that it requires 2026-07-28. The server doesn't need to tell the client.

As a side note, even ignoring what I'm saying here, requires.protocolVersion is just redundant in server/discover because that method explicitly only returns capabilities for the negotiated protocol version: so if a client sends a request with 2025-11-25, the server just omits the tasks extension entirely because it isn't available in the negotiated version.

Minor changes

For minor changes we already have a way to advertise those: extension capabilities. If you e.g. introduce event streaming to tasks as an optional add-on (backwards compatible) then you just add an eventSource: {} to the extension capability schema and negotiate the same way that base protocol negotiation happens.

This is actually better than minor versions in my opinion since it allows servers to declare different subsets of additive features rather than 1.2.3 meaning that you support everything from all prior versions.

Patch versions themselves are pure ceremony. By definition, they MUST NOT affect interoperability, so they by definition cannot be part of protocol semantics.

A semver version might be useful metadata (similar to serverVersion), for logging/auditing etc. - but I don't think it needs to participate in the protocol or have any semantics. I'd be in favor of extension version as a pure metadata/telemetry field.

Breaking changes

This SEP says there's no way for major version to co-exist, but I don't see why not. You call server/discover, it says it supports tasks and tasks-v2 and the client chooses whichever is preferable (again, the client knows about both these extensions, so it knows that one may supersede the other).

The benefit of have separate extension IDs is that you can have a separate capabilities schema for each one (which is 100% necessary, because the schemas may not be compatible).

---

What I do think we're missing from extensions (which is only tangentially related to this) is a concept of stability, i.e. people using extension what to know "is this beta, is it going to break, how long are deprecation periods?" etc. This is not protocol, but it's related to versioning and is something we should solve.

[LucaButBoring]

What this means is that a server telling the client that Tasks v1.2.3 requires 2026-07-28 is just redundant. The client already knows this because it implements Tasks and the Tasks extension says that it requires 2026-07-28. The server doesn't need to tell the client.

As a side note, even ignoring what I'm saying here, requires.protocolVersion is just redundant in server/discover because that method explicitly only returns capabilities for the negotiated protocol version: so if a client sends a request with 2025-11-25, the server just omits the tasks extension entirely because it isn't available in the negotiated version.

Still chewing on the rest of the feedback, but this point jumped out to me as somewhat imprecise. I think you're basically right that we don't need to declare a protocol floor during capability discovery, but that does not actually mean that the status quo works.

Tasks (as of SEP-2663) depends on subscriptions/listen for delivering task notifications. Consider a case where we decide in the base protocol that it's not the right mechanism for notification delivery, and we summarily remove it. We can declare a required initial protocol version in the Tasks specification, but then we're stuck with either:

1. Being locked to that protocol version and needing to publish a new extension revision whenever a new base protocol version releases, or
2. Declaring a minimum version and just hoping things don't break in new base protocol revisions.

Of those, the former seems like the more-correct option, but it also has its own immediate consequences, for example breaking every existing extension on 7/28. Any way you look at it, that seems like a problem we need to reckon with.

Furthermore, I think it is worth noting that that server/discover does not actually explicitly only return capabilities for the negotiated protocol version, it only implicitly does. That is doubly-important for extensions, as nothing in SEP-2575 specifies that extensions should consider checking the protocol version before registering their own extension capabilities (I wouldn't have considered this when implementing Tasks, at least). Extensions are ostensibly decoupled from the base protocol's release schedule, but this seems to throw a wrench in that, as base protocol releases would then set hard beginning/end periods for the validity of any given extension identifier.