René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:3676f4e1-b23d-42a5-fee0-4041644bae73
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idAAFE:289642:83617B:B50ABF:6B009F0E
html-safe-nonce096aeeb0d065acbb755fbd2578562665c6ede21d1490baef98036f55db84b020
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBQUZFOjI4OTY0Mjo4MzYxN0I6QjUwQUJGOjZCMDA5RjBFIiwidmlzaXRvcl9pZCI6Ijg1NjY4MDcyNDcxNzMyMzAzNTAiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac7dacd1b8e586a52db4dbc93ff4b2eec5b4d87f14168f93df4f51892ce2581062
hovercard-subject-tagissue:5155818780
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/modelcontextprotocol/python-sdk/3309/issue_layout
twitter:imagehttps://opengraph.githubassets.com/578ce1ca7fa911e631148a5c61d5c492740532f56f65780c06a441a0099a0258/modelcontextprotocol/python-sdk/issues/3309
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/578ce1ca7fa911e631148a5c61d5c492740532f56f65780c06a441a0099a0258/modelcontextprotocol/python-sdk/issues/3309
og:image:altProblem 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:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamehaiiibin
hostnamegithub.com
expected-hostnamegithub.com
None52c95ce7e48016ae14399656b4ee812462b6f1fa28c5008c8394da64794c00b8
turbo-cache-controlno-preview
go-importgithub.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git
octolytics-dimension-user_id182288589
octolytics-dimension-user_loginmodelcontextprotocol
octolytics-dimension-repository_id862584018
octolytics-dimension-repository_nwomodelcontextprotocol/python-sdk
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id862584018
octolytics-dimension-repository_network_root_nwomodelcontextprotocol/python-sdk
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release1c9ddec8215f9a94e295c8310c3579b9c54ba31a
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/modelcontextprotocol/python-sdk/issues/3309#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2F3309
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2F3309
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=modelcontextprotocol%2Fpython-sdk
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3309
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3309
Reloadhttps://github.com/modelcontextprotocol/python-sdk/issues/3309
modelcontextprotocolhttps://github.com/modelcontextprotocol
python-sdkhttps://github.com/modelcontextprotocol/python-sdk
Codehttps://github.com/modelcontextprotocol/python-sdk
Issues308 (308)https://github.com/modelcontextprotocol/python-sdk/issues
Pull requests112 (112)https://github.com/modelcontextprotocol/python-sdk/pulls
Actionshttps://github.com/modelcontextprotocol/python-sdk/actions
Projectshttps://github.com/modelcontextprotocol/python-sdk/projects
Security and quality12 (12)https://github.com/modelcontextprotocol/python-sdk/security
Insightshttps://github.com/modelcontextprotocol/python-sdk/insights
https://github.com/modelcontextprotocol/python-sdk
New issuehttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3309
New issuehttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3309
docs: no guidance for supporting SDK 1.x and 2.x at the same timehttps://github.com/modelcontextprotocol/python-sdk/issues/3309#top
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Aug 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issue-5155818780
data-profiler-mcphttps://github.com/haiiibin/data-profiler-mcp
acb-tax-mcphttps://github.com/haiiibin/acb-tax-mcp
Trim the migration guide to genuine v1-to-v2 breaking changes #3183https://github.com/modelcontextprotocol/python-sdk/pull/3183
https://github.com/MilkyWay008
MilkyWay008https://github.com/MilkyWay008
on Aug 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5298962316
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Aug 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5299230642
https://github.com/maxisbey
maxisbeyhttps://github.com/maxisbey
on Aug 17, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5319924568
anthropics/anthropic-sdk-python@8b327c3https://github.com/anthropics/anthropic-sdk-python/commit/8b327c35c35efda455dba5be6aeaea04672eb760
https://github.com/pragati243
pragati243https://github.com/pragati243
on Aug 18, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5324153914
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Aug 18, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5324267609
@maxisbeyhttps://github.com/maxisbey
main...haiiibin:docs-dual-version-supporthttps://github.com/modelcontextprotocol/python-sdk/compare/main...haiiibin:python-sdk:docs-dual-version-support
@pragati243https://github.com/pragati243
https://github.com/pragati243
pragati243https://github.com/pragati243
on Aug 18, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5324355254
maxisbeyhttps://github.com/maxisbey
v1Affects the v1.x maintenance linehttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v1%22
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
v1Affects the v1.x maintenance linehttps://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v1%22
on Aug 18, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#event-29625189092
https://github.com/nortesoftware
nortesoftwarehttps://github.com/nortesoftware
on Sep 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5665825169
haiiibinhttps://github.com/haiiibin
on Sep 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#event-31114030816
docs: add a page on supporting SDK v1 and v2 at the same timehttps://github.com/haiiibin/python-sdk/commit/9e44c16af6d86226b670158e0ab649b4c56e687a
9e44c16https://github.com/haiiibin/python-sdk/commit/9e44c16af6d86226b670158e0ab649b4c56e687a
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Sep 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5666968099
@nortesoftwarehttps://github.com/nortesoftware
Point imports of mcp.server.fastmcp at the migration guide #3388https://github.com/modelcontextprotocol/python-sdk/pull/3388
Point imports of mcp.server.fastmcp at the migration guide #3388https://github.com/modelcontextprotocol/python-sdk/pull/3388
Point imports of mcp.server.fastmcp at the migration guide #3388https://github.com/modelcontextprotocol/python-sdk/pull/3388
main...haiiibin:docs-dual-version-supporthttps://github.com/modelcontextprotocol/python-sdk/compare/main...haiiibin:python-sdk:docs-dual-version-support
@maxisbeyhttps://github.com/maxisbey
https://github.com/nortesoftware
nortesoftwarehttps://github.com/nortesoftware
on Sep 14, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5671194333
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Sep 17, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5709628727
@nortesoftwarehttps://github.com/nortesoftware
diffhttps://github.com/haiiibin/python-sdk/commit/0fb034b
https://github.com/nortesoftware
nortesoftwarehttps://github.com/nortesoftware
on Sep 26, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5843049275
https://github.com/maxisbey
maxisbeyhttps://github.com/maxisbey
on Oct 1, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-5934335796
migration guidehttps://py.sdk.modelcontextprotocol.io/migration/
#3388https://github.com/modelcontextprotocol/python-sdk/pull/3388
AI Disclaimerhttps://gist.github.com/maxisbey/6123d132484e4c533eab519a2800693d
maxisbeyhttps://github.com/maxisbey
not plannedhttps://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Anot-planned
on Oct 1, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#event-32263668990
https://github.com/haiiibin
haiiibinhttps://github.com/haiiibin
on Oct 9, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#issuecomment-6074802760
#3388https://github.com/modelcontextprotocol/python-sdk/pull/3388
@nortesoftwarehttps://github.com/nortesoftware
haiiibinhttps://github.com/haiiibin
on Oct 9, 2026https://github.com/modelcontextprotocol/python-sdk/issues/3309#event-32895978047
Drop MCP SDK 1.x support (0.4.0)https://github.com/haiiibin/data-profiler-mcp/commit/1387860dda0ffcef01d7304b3dad94cf71c5b997
1387860https://github.com/haiiibin/data-profiler-mcp/commit/1387860dda0ffcef01d7304b3dad94cf71c5b997
Drop MCP SDK 1.x support (0.5.0)https://github.com/haiiibin/acb-tax-mcp/commit/997bf9b2e41a72055df963ab5075034888ce45e7
997bf9bhttps://github.com/haiiibin/acb-tax-mcp/commit/997bf9b2e41a72055df963ab5075034888ce45e7
Sign up for freehttps://github.com/signup?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3309
Sign in to commenthttps://github.com/login?return_to=https://github.com/modelcontextprotocol/python-sdk/issues/3309
v2Affects the v2 line (2.x on main)https://github.com/modelcontextprotocol/python-sdk/issues?q=state%3Aopen%20label%3A%22v2%22
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.