René's URL Explorer Experiment


Title: Trim the migration guide to genuine v1-to-v2 breaking changes by maxisbey · Pull Request #3183 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Trim the migration guide to genuine v1-to-v2 breaking changes by maxisbey · Pull Request #3183 · modelcontextprotocol/python-sdk

X Title: Trim the migration guide to genuine v1-to-v2 breaking changes by maxisbey · Pull Request #3183 · modelcontextprotocol/python-sdk

Description: Cuts docs/migration.md down to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Rebased onto current main (post-2.1.1) with every example re-verified against today's v1.x and main. Motivation and Context The guide had drifted into a changelog: new-in-v2 feature notes, "what did not change" inventories, spec-adoption commentary, deprecations of APIs that still work, and internal fixes with nothing for a migrator to change, alongside stale before/after code and a fair amount of history narration. A porter (or an agent pointed at the page) had to sieve for the parts that apply. What changed: Removed non-migration entries (102 → 80 sections): the whole Deprecations group, the "what did not change" sections, the mcp dev/mcp install pinning note, the 4 MiB body limit (also on v1.x; kept as a clause beside max_request_body_size), the resolver capability gate, the stdio_client shutdown rework, SEP-2352/SEP-2350 adoption, lowlevel-handler registration through private attributes, the subscribe-capability fix, client_secret_post/-32601 wire notes, and the Mcp-Param-* section. The two deprecation consequences a migrator does act on stay, under Testing utilities: warnings-as-errors suites failing on MCPDeprecationWarning, and the client calls that go dead on the default 2026-era Client(server) connection (mode="legacy" restores them). Corrected code and claims against current 2.x: mcp.types is a permanent alias (imports keep working), issuer= on the client-credentials providers, session_idle_timeout/max_sessions in the moved-parameters list, UnexpectedToolError on direct call_tool(), the removed ValidationError, PRM discovery failures, and more. Every remaining before/after block was executed or import-checked against v1.x and main. Two entries added for 2.1 behavior the guide never recorded: exception messages from @mcp.tool() handlers no longer reach the model unless raised as ToolError, and content-block return annotations no longer produce output_schema/structured_content. Reframed "Notes for 2026-era connections" as "Behavior changes on v2's default connection" (symptom-first: NoBackChannelError, log opt-in, listen-only change notifications), folded near-duplicates (dependency requirements, default server identity, direct calls to MCPServer protocol methods, the in-memory testing helper), standardized imports, regenerated the index and suggested-order blocks, and cut history and over-explanation throughout. How Has This Been Tested? Each surviving example was executed or import-checked against the corresponding tree (v1.x for "Before", main for "After"), driving handler code through the in-memory client where relevant. scripts/docs/build.sh (strict Zensical build, render-order and cross-reference checks) and markdownlint pass; every intra-document anchor resolves under both GitHub and Python-Markdown slug rules, and the headings other pages (and the mcp.server.fastmcp shim message) link to are unchanged. Breaking Changes None — documentation only. 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 Also touches docs/whats-new.md, only to drop two links whose target sections this removes (mcp dev/mcp install pinning and Mcp-Param-*); the strict build aborts on missing anchors. migration.md is excluded from translation, but the translated whats-new.md pages still carry those two links until the translation tool is next run (their builds are non-strict, so this is a warning, not a failure). AI Disclaimer

Open Graph Description: Cuts docs/migration.md down to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Rebased onto current main (p...

X Description: Cuts docs/migration.md down to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Rebased onto current main (p...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3183

X: @github

direct link

Domain: github.com

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/:user_id/:repository/pull/:id/files(.:format)
route-controllerpull_requests
route-actionfiles
fetch-noncev2:f03d6a00-a029-d98b-dad1-d717da1e68c9
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idE438:1A2DA6:9FD6C8:DB694B:6B00A744
html-safe-nonce84f2c24af31d21c423b6c10acf35d716406dba1dcd8ec6b88d08ecb95c210ca5
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFNDM4OjFBMkRBNjo5RkQ2Qzg6REI2OTRCOjZCMDBBNzQ0IiwidmlzaXRvcl9pZCI6IjU5MDE3MjAxMjA5MTY0ODU5NTYiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac985df37825dd9d5d1c8288f87a55720a8dfb747cedcf15f6b51ada99e97a234f
hovercard-subject-tagpull_request:4138082466
github-keyboard-shortcutsrepository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///pull_requests/show/files
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/3183/files
twitter:imagehttps://avatars.githubusercontent.com/u/224885523?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/224885523?s=400&v=4
og:image:altCuts docs/migration.md down to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Rebased onto current main (p...
og:site_nameGitHub
og:typeobject
hostnamegithub.com
expected-hostnamegithub.com
None455b493e3402a3a3a06beac5d20bb7db3da060808b220aa48d6a7eca7c59863a
turbo-cache-controlno-preview
diff-viewunified
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 full-width
disable-turbotrue
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release2f575159976167242d488c0b062eb355c4e198b7
ui-targetfull
theme-color#1e2327
color-schemelight dark

Links:

Skip to contenthttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F3183%2Ffiles
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%2Fpull%2F3183%2Ffiles
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=modelcontextprotocol%2Fpython-sdk
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
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
Sign up for GitHub https://github.com/signup?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
terms of servicehttps://docs.github.com/terms
privacy statementhttps://docs.github.com/privacy
Sign inhttps://github.com/login?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
maxisbeyhttps://github.com/maxisbey
mainhttps://github.com/modelcontextprotocol/python-sdk/tree/main
migration-doc-cleanuphttps://github.com/modelcontextprotocol/python-sdk/tree/migration-doc-cleanup
Conversation 3 https://github.com/modelcontextprotocol/python-sdk/pull/3183
Commits 1 https://github.com/modelcontextprotocol/python-sdk/pull/3183/commits
Checks 39 https://github.com/modelcontextprotocol/python-sdk/pull/3183/checks
Files changed https://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Trim the migration guide to genuine v1-to-v2 breaking changes https://github.com/modelcontextprotocol/python-sdk/pull/3183/files#top
Show all changes 1 commit https://github.com/modelcontextprotocol/python-sdk/pull/3183/files
934a417 Trim the migration guide to genuine v1-to-v2 breaking changes maxisbey Sep 4, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3183/commits/934a417e29051f70aaf65d49b36b21d80eb49e9d
Clear filters https://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
migration.md https://github.com/modelcontextprotocol/python-sdk/pull/3183/files#diff-758ba107a728fccfdf0d098b2c06ded59127dd53ea287d630f72fb51040bc72d
whats-new.md https://github.com/modelcontextprotocol/python-sdk/pull/3183/files#diff-9428ccc149911a1fdbacb719bfe6f6e4d0c4fbe84f4ce18d14cdb5cd82b9df45
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3183/files
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.