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
Domain: github.com
| 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 | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:f03d6a00-a029-d98b-dad1-d717da1e68c9 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | E438:1A2DA6:9FD6C8:DB694B:6B00A744 |
| html-safe-nonce | 84f2c24af31d21c423b6c10acf35d716406dba1dcd8ec6b88d08ecb95c210ca5 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFNDM4OjFBMkRBNjo5RkQ2Qzg6REI2OTRCOjZCMDBBNzQ0IiwidmlzaXRvcl9pZCI6IjU5MDE3MjAxMjA5MTY0ODU5NTYiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 985df37825dd9d5d1c8288f87a55720a8dfb747cedcf15f6b51ada99e97a234f |
| hovercard-subject-tag | pull_request:4138082466 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,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/modelcontextprotocol/python-sdk/pull/3183/files |
| twitter:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| og:image:alt | 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... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | 455b493e3402a3a3a06beac5d20bb7db3da060808b220aa48d6a7eca7c59863a |
| turbo-cache-control | no-preview |
| diff-view | unified |
| 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 full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 2f575159976167242d488c0b062eb355c4e198b7 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width