From 5a6222073680a487afd7cd4669831d1097dba0e7 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Wed, 29 Jul 2026 13:39:09 +0000 Subject: [PATCH 1/2] Link the released 2026-07-28 spec and point migrators at /v1/ The README banner still linked the spec's release-candidate blog post; the specification is now published, so link it directly. Also give the migration guide's help section the same pointer to the v1.x maintenance-line docs that index.md and whats-new.md already carry. No-Verification-Needed: doc-only change --- README.md | 2 +- docs/migration.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b14a8e120..1850141b6 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ > [!NOTE] -> **This is v2 of the MCP Python SDK, the current stable release line.** It is a major rework of the SDK, both to support the [2026-07-28 MCP specification](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/) for the tour of what changed and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for every breaking change. +> **This is v2 of the MCP Python SDK, the current stable release line.** It is a major rework of the SDK, both to support the [2026-07-28 MCP specification](https://modelcontextprotocol.io/specification/2026-07-28) (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/) for the tour of what changed and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for every breaking change. > > **Not ready to migrate?** v1.x lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x), continues to receive critical bug fixes and security patches, and is documented at . Since `pip install mcp` now installs 2.x, keep a `<2` upper bound on your requirement (for example `mcp>=1.28,<2`) until you've migrated. > diff --git a/docs/migration.md b/docs/migration.md index 931d470d1..456a88fbc 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -2877,3 +2877,6 @@ If you encounter issues during migration: 1. Check the [API Reference](api/mcp/index.md) for updated method signatures 2. Review the [examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples) for updated usage patterns 3. Open an issue on [GitHub](https://github.com/modelcontextprotocol/python-sdk/issues) if you find a bug or need further assistance + +Not ready to migrate yet? The v1.x maintenance line keeps receiving critical bug fixes and security +patches; its documentation is at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/). From 058dc8febbcad3e34cd10758a7fbd669ac70c8b0 Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Wed, 29 Jul 2026 13:56:42 +0000 Subject: [PATCH 2/2] Move the "not ready to migrate" note to the top of the guide Put it right under the intro as an admonition, matching the "Coming from v1?" note elsewhere, instead of at the end of the Need Help section where nobody scrolls to. No-Verification-Needed: doc-only change --- docs/migration.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index 456a88fbc..b094d79f8 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -4,6 +4,11 @@ This guide covers the breaking changes introduced in v2 of the MCP Python SDK an Version 2 of the MCP Python SDK introduces several breaking changes to improve the API, align with the MCP specification, and provide better type safety. +!!! note "Not ready to migrate yet?" + The v1.x maintenance line keeps receiving critical bug fixes and security patches, and its + documentation is at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/). If your package depends + on `mcp`, keep a `<2` upper bound until you've migrated. + ## Find your changes Every section heading below names the API it affects, so searching this page for the symbol your code uses is the fastest route to the change that broke it. The guide lists changes only: an SDK API not mentioned here behaves as it did in v1, and the "what did not change" summaries — [`MCPServer`](#what-is-unchanged-on-mcpserver), [lowlevel `Server`](#lowlevel-server-what-did-not-change), and [auth](#unchanged-auth-surfaces) — spell out the surfaces most migrators stop to check. @@ -2877,6 +2882,3 @@ If you encounter issues during migration: 1. Check the [API Reference](api/mcp/index.md) for updated method signatures 2. Review the [examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples) for updated usage patterns 3. Open an issue on [GitHub](https://github.com/modelcontextprotocol/python-sdk/issues) if you find a bug or need further assistance - -Not ready to migrate yet? The v1.x maintenance line keeps receiving critical bug fixes and security -patches; its documentation is at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/).