v2.0.0a1

First V2 Alpha Release

This is the first alpha of v2 of the MCP Python SDK.

Publishing this alpha changes nothing for existing users. Installers don't pick up pre-releases unless you explicitly opt in, so if you do nothing you stay on v1.x.

Why v2

The upcoming MCP spec release (2026-07-28) has significant protocol changes, including moving from a stateful, bidirectional protocol to stateless request/response. The v1 SDK is built around long-lived sessions, so supporting the new spec means replacing the SDK's core. Since that's breaking anyway, v2 also fixes some long-standing API problems.

What's in this alpha

• A new Dispatcher pipeline replaces ServerSession on the server side (ServerSession remains as a thin proxy). The same change is coming to ClientSession, which will most likely stay as a shim.
• The low level Server interface has changed quite a bit: handlers are now constructor parameters instead of decorators, and return values are no longer auto-wrapped.
• Server middleware, partially added.
• Type changes throughout, including snake_case field names and stricter validation.
• FastMCP is renamed to MCPServer.

The full list is in the migration guide, which is currently the most complete documentation for v2.

NOTE: that this alpha release only implements the 2025-11-25 spec revision. Support for 2026-07-28 feature will be added over time through each alpha release with full 2026-07-28 support targeted for beta release on 2026-06-30.

Stability and timeline

Right now v2 is very breaking, and each alpha will likely contain breaking changes from the previous one, so pin exact versions if you try it. Before the stable release we plan to add a good amount of backwards compatibility shims to reduce the breakage.

Alphas run from now through late June, with a beta targeted for 2026-06-30 and stable v2 targeted for 2026-07-27 (the spec releases 2026-07-28). v1.x is the only stable version of the SDK for now: it stays in maintenance mode and continues to get critical bug fixes and security patches.

TLDR:

• Today (v2.0.0.a1) - Only 2025-11-25 spec functionality support
• Today -> 2026-06-30 - New MCP 2026-07-28 spec functionality will be added to v2 alpha versions and released regularly during this time
  • Each alpha release during this should be considered breaking
• 2026-06-30 (estimated) - A beta version of the SDK will be released with full MCP 2026-07-28 spec support
• 2026-07-01 -> 2026-07-27 - Bug fixes and cleanup
  • Ideally significantly less breaking that each alpha release, although not guaranteed
• 2026-07-28 - A stable v2.0.0 version of the Python SDK will be released along side the MCP 2026-07-28 spec release.

What you should do

If you maintain a package that depends on mcp, add an upper bound now. 84% of the 10,000+ PyPI packages that depend on mcp declare no upper bound, and they'll all resolve to v2 the day the stable release ships. Add <2 to your existing constraint, for example mcp>=1.27,<2, and your users stay on v1 until you've migrated.

If you want to try v2:

pip install mcp==2.0.0a1
# or
uv add mcp==2.0.0a1

One ask: only pin an mcp pre-release from a pre-release of your own package, otherwise you'll drag your users onto the alpha.

Feedback is much appreciated in #python-sdk-dev on the MCP Contributors Discord, or open an issue with the v2-alpha label.

v1.27.2

What's Changed

• [v1.x] ci: deploy docs to py.sdk.modelcontextprotocol.io via Pages artifact by @maxisbey in #2635
• [v1.x] Add subject and claims to AccessToken by @maxisbey in #2690
• [v1.x] Bind transport sessions to the authenticated principal by @maxisbey in #2719
• [v1.x] Scope experimental tasks to the session that created them by @maxisbey in #2720

Full Changelog: v1.27.1...v1.27.2

v1.27.1

What's Changed

• [v1.x] fix: catch PydanticUserError when generating output schema (pydantic 2.13 compat) by @maxisbey in #2435
• [v1.x] fix(auth): coerce empty-string optional URL fields to None in OAuthClientMetadata by @felixweinberger in #2405
• [v1.x] build: restrict httpx to <1.0.0 by @maxisbey in #2559
• [v1.x] refactor: import SSEError from httpx_sse public API by @maxisbey in #2561

Full Changelog: v1.27.0...v1.27.1

v1.27.0

What's Changed

• fix: remove unused requests dependency from simple-chatbot example by @maxisbey in #1959
• ci: backport conformance tests from main to v1.x by @felixweinberger in #2068
• fix: add RFC 8707 resource validation to OAuth client by @felixweinberger in #2069
• feat: add idle timeout for StreamableHTTP sessions by @felixweinberger in #1994
• [v1.x] fix: prevent command injection in example URL opening by @maxisbey in #2085
• Add VERSIONING.md, ROADMAP.md, and DEPENDENCY_POLICY.md by @felixweinberger in #2084
• docs: restructure README into docs/ pages by @felixweinberger in #2091
• docs: comprehensive feature documentation for SEP-1730 Tier 1 by @felixweinberger in #2090
• docs: fix stub pages and improve docs structure by @felixweinberger in #2101
• docs: fix GitHub links to point to v1.x branch by @felixweinberger in #2102
• docs: add snippet verification for docs/ pages by @felixweinberger in #2115
• docs: add server-side tool error handling documentation by @felixweinberger in #2129
• Backport: Add missing TasksCallCapability to v1.x by @BabyChrist666 in #2137
• [v1.x] fix: handle non-UTF-8 bytes in stdio server stdin by @maxisbey in #2303
• [v1.x] fix: handle ClosedResourceError when transport closes mid-request by @owendevereaux in #2334

New Contributors

• @owendevereaux made their first contribution in #2334

Full Changelog: v1.26.0...v1.27.0

v1.26.0

What's Changed

• ci: add all-green job to pull-request-checks workflow by @maxisbey in #1929
• Backport: Support for Resource and ResourceTemplate metadata by @maxisbey in #1928
• [v1.x] fix: return HTTP 404 for unknown session IDs instead of 400 by @LucaButBoring in #1945

Full Changelog: v1.25.0...v1.26.0

v1.25.0

Branching Update

Starting with this release, the repository has adopted a new branching strategy for v2 development:

• main — v2 development (breaking changes)
• v1.x — v1 maintenance (security and critical bug fixes only, with very rare feature additions ported from main)

Users who need to stay on v1.x should pin to mcp>=1.25,<2.

The current plan is to work through v2 and have it released some time in Q1. This also relies on the next upcoming spec release which will heavily change how the transport layer works, which in turn will guide a lot of how we architect v2.

---

What's Changed

• Fix for Url Elicitation issue 1768 by @gopitk in #1780
• ci: add v1.x branch to main-checks workflow by @maxisbey in #1802

New Contributors

• @gopitk made their first contribution in #1780

Full Changelog: v1.24.0...v1.25.0

v1.24.0

What's Changed

• feat: client-side support for SEP-1577 sampling with tools by @jlowin in #1722
• Fix JSON-RPC error response ID matching by @crondinini-ant in #1720
• Add streamable_http_client which accepts httpx.AsyncClient instead of httpx_client_factory by @Kludex in #1177
• fix: use correct python command name in test_stdio.py by @WOnder93 in #1782

New Contributors

• @WOnder93 made their first contribution in #1782

Full Changelog: v1.23.3...v1.24.0

v1.23.3

What's Changed

• refactor(auth): remove unused _register_client method by @maxisbey in #1748
• feat: add workflow to comment on PRs when released by @felixweinberger in #1750
• fix: allow MIME type parameters in resource validation (RFC 2045) by @antonpk1 in #1755
• Skip empty SSE data to avoid parsing errors by @injusticescorpio in #1753
• chore: remove release-comment workflow by @maxisbey in #1758

New Contributors

• @antonpk1 made their first contribution in #1755
• @injusticescorpio made their first contribution in #1753

Full Changelog: v1.23.2...v1.23.3

v1.23.2

What's Changed

• fix: add lifespan context manager to StreamableHTTP mounting examples by @TheMailmans in #1669
• fix: handle ClosedResourceError in StreamableHTTP message router by @Edison-A-N in #1384
• fix: skip priming events and close_sse_stream for old protocol versions by @felixweinberger in #1719

New Contributors

• @TheMailmans made their first contribution in #1669
• @Edison-A-N made their first contribution in #1384

Full Changelog: v1.23.1...v1.23.2

v1.23.1

What's Changed

• chore: update LATEST_PROTOCOL_VERSION to 2025-11-25 by @felixweinberger in #1715

Full Changelog: v1.23.0...v1.23.1