Title: docs: no guidance for supporting SDK 1.x and 2.x at the same time · Issue #3309 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: docs: no guidance for supporting SDK 1.x and 2.x at the same time · Issue #3309 · modelcontextprotocol/python-sdk
X Title: docs: no guidance for supporting SDK 1.x and 2.x at the same time · Issue #3309 · modelcontextprotocol/python-sdk
Description: Problem docs/migration.md is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaining a published MCP server or library whi...
Open Graph Description: Problem docs/migration.md is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaini...
X Description: Problem docs/migration.md is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaini...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/issues/3309
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"docs: no guidance for supporting SDK 1.x and 2.x at the same time","articleBody":"### Problem\n\n`docs/migration.md` is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaining a published MCP server or library while the ecosystem is split across both majors.\n\nConcretely: the day 2.0.0 shipped, fresh installs of our published servers started resolving `mcp==2.0.0` and crashed at import (`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`), while existing users were still on 1.x. The realistic fix for a package author in that window is not \"migrate\", it is \"support both majors for a transition period\". I could not find a recipe for that anywhere in `docs/`.\n\n### What we ended up doing\n\nRunning in production since late July on two registry-listed servers ([data-profiler-mcp](https://github.com/haiiibin/data-profiler-mcp), [acb-tax-mcp](https://github.com/haiiibin/acb-tax-mcp)):\n\n```python\ntry:\n # MCP SDK 2.x: FastMCP was renamed to MCPServer and the module moved.\n from mcp.server.mcpserver import MCPServer as FastMCP\nexcept ImportError:\n # MCP SDK 1.x keeps the original path.\n from mcp.server.fastmcp import FastMCP\n```\n\ntogether with:\n\n- a dependency pin of `mcp>=1.2.0,\u003c3` so installs may resolve either major, and\n- a dedicated CI job that force-installs `\"mcp>=1.2.0,\u003c2\"` and re-runs the test suite, so the 1.x fallback path stays tested while the main matrix resolves 2.x.\n\nFor code that stays on the FastMCP-level API surface (constructor, `@mcp.tool()`, `run()`), this has been sufficient: both lines pass the same test suite unchanged.\n\n### Proposal\n\nA short section, roughly \"Supporting 1.x and 2.x during the transition\", covering:\n\n1. the import shim above,\n2. dependency-pin guidance (`mcp>=1.2.0,\u003c3`, and why an upper bound of `\u003c2` alone strands your users),\n3. testing both lines in CI (one extra pinned job is enough), and\n4. a sentence on when to drop the 1.x path.\n\nI would keep it to roughly 40 to 60 lines.\n\n### Scoping questions before I write anything\n\n- #3183 is trimming `migration.md` down to genuine breaking changes, so this may not belong there. Would you rather see it as a short section in `migration.md`, or as a separate small docs page (e.g. `docs/compatibility.md`)?\n- If the answer is \"we deliberately do not want to encourage dual-major support\", that is a fair position; happy to close.\n\nIf maintainers think it is worth having, I will send the PR.\n","author":{"url":"https://github.com/haiiibin","@type":"Person","name":"haiiibin"},"datePublished":"2026-08-14T21:34:24Z","url":"https://github.com/modelcontextprotocol/python-sdk/issues/3309"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:3676f4e1-b23d-42a5-fee0-4041644bae73 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | AAFE:289642:83617B:B50ABF:6B009F0E |
| html-safe-nonce | 096aeeb0d065acbb755fbd2578562665c6ede21d1490baef98036f55db84b020 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBQUZFOjI4OTY0Mjo4MzYxN0I6QjUwQUJGOjZCMDA5RjBFIiwidmlzaXRvcl9pZCI6Ijg1NjY4MDcyNDcxNzMyMzAzNTAiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 7dacd1b8e586a52db4dbc93ff4b2eec5b4d87f14168f93df4f51892ce2581062 |
| hovercard-subject-tag | issue:5155818780 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3309/issue_layout |
| twitter:image | https://opengraph.githubassets.com/578ce1ca7fa911e631148a5c61d5c492740532f56f65780c06a441a0099a0258/modelcontextprotocol/python-sdk/issues/3309 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/578ce1ca7fa911e631148a5c61d5c492740532f56f65780c06a441a0099a0258/modelcontextprotocol/python-sdk/issues/3309 |
| og:image:alt | Problem docs/migration.md is a one-way guide: it tells you what to change once you move to 2.x. It has no guidance for the case where you cannot hard-cut, which is the situation of anyone maintaini... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | haiiibin |
| hostname | github.com |
| expected-hostname | github.com |
| None | 52c95ce7e48016ae14399656b4ee812462b6f1fa28c5008c8394da64794c00b8 |
| turbo-cache-control | no-preview |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 1c9ddec8215f9a94e295c8310c3579b9c54ba31a |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width