SEP-1309: Add spec and SDK versioning guidelines by pantanurag555 · Pull Request #1404 · modelcontextprotocol/modelcontextprotocol

pantanurag555 · 2025-08-29T22:19:26Z

Motivation and Context

This PR adds the specification and SDK versioning guidelines introduced in the accepted #1309 to the specification documentation.

How Has This Been Tested?

Tested locally using the instructions in CONTRIBUTING.md.

Breaking Changes

None

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

There is some confusion regarding the best place to add these guidelines. The implementation tracking matrix should live in the SDKs section under Documentation tab. However, I am open to suggestion for the versioning guidelines. Currently I have added them in the Versioning section under Documentation tab. There can also be a case made to break them up and add them to the Governance and Stewardship section under the Community tab or to actually add them within the Specification tab somewhere near the Version Negotiation guidelines. Open to feedback on this.

docs/specification/versioning.mdx

docs/community/governance.mdx

localden · 2025-11-11T06:22:46Z

@pantanurag555 @000-000-000-000-000

👋 just as a reminder, we're aiming to ensure that all SEPs that are on-deck for the 2025-11-25 spec release are verbiage-ready and merged by Friday, November 14, 2025. Please prioritize making the required changes (given that this is accepted with changes, per Core Maintainer review meeting) before then.

docs/community/governance.mdx

localden · 2025-11-11T06:26:32Z

docs/community/governance.mdx

@@ -110,6 +112,29 @@ All proposals must have a **sponsor** from the MCP steering group (maintainer, c

 Once proposals have a sponsor, they are assigned to the sponsor and are tagged `draft`.

+### SDK Versioning
+
+SDK maintainers have the freedom to do SDK version releases at their own pace. Each SDK version release **SHOULD** contain, as part of its code, the specification versions that are supported by the SDK version release.


This could be reframed.

Suggested change

SDK maintainers have the freedom to do SDK version releases at their own pace. Each SDK version release **SHOULD** contain, as part of its code, the specification versions that are supported by the SDK version release.

SDK maintainers can release new SDK versions at the pace suitable for their respective libraries.

Each SDK release **MUST** be clear about the protocol specification versions that are supported by the library.

I am fine with reframing the first statement. I do want to leave the SHOULD statement in there for the reason I mentioned above. Let me know if you don't agree with having the statement in there.

I have left the SHOULD statement in there but reframed the first sentence. Let me know if you disagree with the current structure.

docs/community/governance.mdx

docs/docs/sdk.mdx

docs/specification/versioning.mdx

localden · 2025-11-11T06:42:53Z

@pantanurag555 another thing to mention is that some SDKs are community-driven. This needs to be captured in the verbiage above.

pantanurag555 · 2025-11-11T20:29:17Z

@localden I was unsure what is the ideal place to mention community-driven in the verbiage given that even those SDKs should have SDK maintainers. Can you suggest where you think it would be appropriate?

pantanurag555 · 2025-11-11T20:40:23Z

@ihrpr Would really appreciate if you could take a look at the PR as well. As discussed in the SDKs WG, the tiering SEP #1730 is also making significant changes around SDK governance. Would appreciate insight on how this PR can align itself and be cohesive with the changes from the tiering SEP.

000-000-000-000-000 · 2025-11-14T21:45:44Z

docs/docs.json

+    {
+      "source": "/docs/concepts/cancellation",
+      "destination": "/specification/2025-06-18/basic/utilities/cancellation"
+    },
+    {
+      "source": "/docs/concepts/ping",
+      "destination": "/specification/2025-06-18/basic/utilities/ping"
+    },
+    {
+      "source": "/docs/concepts/progress",
+      "destination": "/specification/2025-06-18/basic/utilities/progress"
+    },
+    {
+      "source": "/docs/concepts/completion",
+      "destination": "/specification/2025-06-18/server/utilities/completion"
+    },
+    {
+      "source": "/docs/concepts/logging",
+      "destination": "/specification/2025-06-18/server/utilities/logging"
+    },
+    {
+      "source": "/docs/concepts/pagination",
+      "destination": "/specification/2025-06-18/server/utilities/pagination"
+    },


what's this?

These are redirect links that are used for the table. Added a few for the new features that we have used in these tables.

000-000-000-000-000 · 2025-11-14T21:47:15Z

docs/docs/sdk.mdx

+| Specification Version    	|  Status 	| [Typescript] 	| [Python] 	| [Go] 	| [Kotlin] 	| [Swift] 	| [Java] 	| [C#] 	| [Ruby] 	| [Rust] 	|
+|--------------------------	|----------	|--------------	|----------	|------	|----------	|---------	|--------	|------	|--------	|--------	|
+| [2024-11-05][2024-11-05] 	| ✅        	| ❓            	| ❓        	| ❓    	| ❓        	| ❓       	| ❓      	| ❓    	| ❓      	| ❓      	|
+| [2025-03-26][2025-03-26] 	| ✅        	| ❓            	| ❓        	| ❓    	| ❓        	| ❓       	| ❓      	| ❓    	| ❓      	| ❓      	|
+| [2025-06-18][2025-06-18] 	| ✅        	| ❓            	| ❓        	| ❓    	| ❓        	| ❓       	| ❓      	| ❓    	| ❓      	| ❓      	|
+


can we get this filled out? Also what about the thanksgiving spec release?

Added the thanksgiving spec release.

This needs to be filled out by the SDK maintainers since they will be the most familiar with the version releases that are compliant with a given protocol spec (and when support was dropped). Eventually conformance tests can help with filling out this matrix.

000-000-000-000-000 · 2025-11-14T21:47:40Z

docs/docs/sdk.mdx

+
+</div>
+
+### Client Features


what about auth stuff like CIMD?

Auth was discussed but we didn't classify it as a feature to prevent feature creep. I also think of auth as an umbrella term and we would need to go more granular otherwise a simple mark indicating compliance, partial compliance or not compliant won't signify much.

000-000-000-000-000 · 2025-11-14T21:48:50Z

docs/docs/sdk.mdx

+| [Typescript] 	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Python]     	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Go]         	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Kotlin]     	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Swift]      	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Java]       	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [C#]         	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Ruby]       	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+| [Rust]       	| ❓         	| ❓           	| ❓       	| ❓             	| ❓         	| ❓            	|
+


how are we going to get this stuff filled out?

This needs to be filled out by the SDK maintainers since they will be the most intimately familiar with whether a certain feature in an SDK is compliant according to the latest spec version or not.
Eventually this will be updated based on conformance tests specific for each feature (either manually or in an automated manner).

chr-hertel · 2025-11-15T00:01:04Z

currently php sdk is missing 😢

pantanurag555 · 2025-11-15T00:10:20Z

My bad 😅 Adding it right now. Thanks for the callout.

paoloricciuti · 2025-11-15T07:29:14Z

Is this only for the official SDK? I've build an alternative typescript SDK and would be cool to feature community ones.

github-actions · 2026-01-17T20:08:16Z

Maintainer Activity Check

Hi @000-000-000-000-000!

You're assigned to this SEP but there hasn't been any activity from you in 66 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

Add 10 SEPs that were missed during the initial migration in PR #1804: - SEP-991: OAuth Client ID Metadata Documents (Final) - SEP-1024: MCP Client Security Requirements (Final - PR #1025 merged) - SEP-1034: Default values for elicitation schemas (Final) - SEP-1036: URL Mode Elicitation (Final) - SEP-1303: Input Validation Errors (Final) - SEP-1577: Sampling With Tools (Final) - SEP-1613: JSON Schema 2020-12 Default Dialect (Final) - SEP-1686: Tasks (Final) - SEP-1699: SSE Polling via server-side disconnect (Final) - SEP-1730: SDKs Tiering System (Final) Note: SEP-1309 (Specification Version Management) was NOT included as PR #1404 implementing it is still open. Also fixes formatting issues in SEP metadata (Type, Author fields).

sep-automation-bot · 2026-02-02T09:19:13Z

Maintainer Activity Check

Hi @000-000-000-000-000!

You're assigned to this SEP but there hasn't been any activity from you in 15 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

sep-automation-bot · 2026-02-16T09:21:04Z

Maintainer Activity Check

Hi @000-000-000-000-000!

You're assigned to this SEP but there hasn't been any activity from you in 14 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

…ontextprotocol#2136) Add 10 SEPs that were missed during the initial migration in PR modelcontextprotocol#1804: - SEP-991: OAuth Client ID Metadata Documents (Final) - SEP-1024: MCP Client Security Requirements (Final - PR modelcontextprotocol#1025 merged) - SEP-1034: Default values for elicitation schemas (Final) - SEP-1036: URL Mode Elicitation (Final) - SEP-1303: Input Validation Errors (Final) - SEP-1577: Sampling With Tools (Final) - SEP-1613: JSON Schema 2020-12 Default Dialect (Final) - SEP-1686: Tasks (Final) - SEP-1699: SSE Polling via server-side disconnect (Final) - SEP-1730: SDKs Tiering System (Final) Note: SEP-1309 (Specification Version Management) was NOT included as PR modelcontextprotocol#1404 implementing it is still open. Also fixes formatting issues in SEP metadata (Type, Author fields).

sep-automation-bot · 2026-03-09T09:19:22Z

Maintainer Activity Check

Hi @000-000-000-000-000!

You're assigned to this SEP but there hasn't been any activity from you in 20 days.

Please provide an update on:

Current status of your review/work
Any blockers or concerns
Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.

This is an automated message from the SEP lifecycle bot.

pantanurag555 requested review from a team and ihrpr August 29, 2025 22:19

pantanurag555 mentioned this pull request Aug 29, 2025

SEP-1309: Specification Version Management #1309

Closed

LucaButBoring reviewed Aug 29, 2025

View reviewed changes

docs/specification/versioning.mdx Outdated Show resolved Hide resolved

dend added proposal SEP proposal without a sponsor. SEP labels Sep 8, 2025

000-000-000-000-000 reviewed Nov 7, 2025

View reviewed changes

docs/specification/versioning.mdx Outdated Show resolved Hide resolved

pantanurag555 force-pushed the main branch from cf2ee2c to f3fa8c8 Compare November 10, 2025 21:20

pantanurag555 requested a review from a team as a code owner November 10, 2025 21:20

pantanurag555 requested a review from a team November 10, 2025 21:20

pantanurag555 force-pushed the main branch from f3fa8c8 to 82f78d2 Compare November 10, 2025 21:30

pantanurag555 requested a review from 000-000-000-000-000 November 10, 2025 22:13

000-000-000-000-000 reviewed Nov 10, 2025

View reviewed changes

docs/community/governance.mdx Outdated Show resolved Hide resolved

000-000-000-000-000 reviewed Nov 10, 2025

View reviewed changes

docs/community/governance.mdx Outdated Show resolved Hide resolved

docs/community/governance.mdx Outdated Show resolved Hide resolved

pantanurag555 requested a review from 000-000-000-000-000 November 10, 2025 23:13

localden linked an issue Nov 11, 2025 that may be closed by this pull request

SEP-1309: Specification Version Management #1309

Closed

localden requested changes Nov 11, 2025

View reviewed changes

pantanurag555 force-pushed the main branch from f1cacfc to 24122e9 Compare November 11, 2025 20:26

pantanurag555 requested a review from localden November 11, 2025 20:29

dend assigned 000-000-000-000-000 Nov 12, 2025

pantanurag555 force-pushed the main branch 2 times, most recently from 029f75c to 7159338 Compare November 14, 2025 21:42

000-000-000-000-000 reviewed Nov 14, 2025

View reviewed changes

pantanurag555 force-pushed the main branch from 7159338 to 80c37cc Compare November 14, 2025 23:46

SEP-1309: Add spec and SDK versioning guidelines

30eaef7

pantanurag555 force-pushed the main branch from 80c37cc to 30eaef7 Compare November 15, 2025 00:20

pantanurag555 requested a review from 000-000-000-000-000 November 15, 2025 00:20

dsp-ant added draft SEP proposal with a sponsor. and removed proposal SEP proposal without a sponsor. labels Jan 17, 2026

localden added this to SEP Review Pipeline Jan 21, 2026

localden moved this to Draft in SEP Review Pipeline Jan 21, 2026

dsp-ant mentioned this pull request Jan 22, 2026

Migrate remaining SEPs missed in PR #1804 #2136

Merged

-SDK maintainers have the freedom to do SDK version releases at their own pace. Each SDK version release **SHOULD** contain, as part of its code, the specification versions that are supported by the SDK version release.
+SDK maintainers can release new SDK versions at the pace suitable for their respective libraries.
+Each SDK release **MUST** be clear about the protocol specification versions that are supported by the library.


		</div>

		### Client Features

Conversation

pantanurag555 commented Aug 29, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden commented Nov 11, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden commented Nov 11, 2025

Uh oh!

pantanurag555 commented Nov 11, 2025

Uh oh!

pantanurag555 commented Nov 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chr-hertel commented Nov 15, 2025

Uh oh!

pantanurag555 commented Nov 15, 2025

Uh oh!

paoloricciuti commented Nov 15, 2025

Uh oh!

github-actions bot commented Jan 17, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot bot commented Feb 2, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot bot commented Feb 16, 2026

Maintainer Activity Check

Uh oh!

sep-automation-bot bot commented Mar 9, 2026

Maintainer Activity Check

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants