mcp 2.0.0a2

v2.0.0a2

on Python PyPI

Second v2 alpha. Pre-releases are opt-in only; pip install mcp still resolves to the stable 1.x line.

pip install mcp==2.0.0a2
# or
uv add "mcp==2.0.0a2"

See the migration guide for the full list of breaking changes.

Highlights

Full 2026-07-28 types added along with per-version protocol types and version-gated wire validation (#2849)

The SDK now ships three type sets:

• mcp.types - the hand-maintained superset monolith. This remains the public API you import from; it covers every field from every supported spec version.
• mcp.types.v2025_11_25 - generated verbatim from the 2025-11-25 schema (also serves earlier versions).
• mcp.types.v2026_07_28 - generated verbatim from the 2026-07-28 schema.

The generated per-version packages are wired into both ServerRunner and ClientSession via mcp.types.methods, which maps each (method, version) pair to its request/result/notification types. At runtime, the negotiated protocol version selects which generated set is used to validate traffic on the wire:

• Inbound requests and notifications are validated against the negotiated version's types. A spec method that does not exist at that version returns METHOD_NOT_FOUND; a malformed payload returns INVALID_PARAMS.
• Inbound results (in both directions) are validated against the negotiated version's result type before being parsed into the monolith type.
• Outbound results are serialized through the negotiated version's type, so fields that only exist in a newer spec version are stripped before they reach an older peer.

User code keeps working with the monolith mcp.types; the per-version packages are an internal validation layer. 2026-07-28 is modeled but not yet negotiable - SUPPORTED_PROTOCOL_VERSIONS is unchanged in this alpha.

This makes validation stricter than a1: handlers that returned spec-invalid output (for example Tool(inputSchema={}) without "type": "object") now fail with INTERNAL_ERROR, and clients now reject spec-invalid server output that was previously tolerated.

ClientSession now runs on the dispatcher (#2838)

ClientSession has been rewritten to sit on the same JSONRPCDispatcher receive path that ServerRunner adopted in a1, and BaseSession is removed. The public surface (constructor, typed request methods, initialize(), context-manager lifecycle) is unchanged, but the internals fix several long-standing v1 issues:

• Server-initiated requests (sampling, elicitation, roots) now run concurrently instead of inline in the receive loop, so a slow callback no longer blocks the whole session and a callback that itself sends a request no longer deadlocks.
• A raising notification or request callback is contained at the dispatcher and no longer takes down the connection.
• Timed-out or caller-cancelled requests now send notifications/cancelled to the peer.
• Server-to-client cancellation now actually interrupts the running client callback.

A new keyword-only dispatcher= constructor argument lets you pass a pre-built dispatcher (for example DirectDispatcher for in-process embedding) instead of the read/write stream pair.

What's Changed

• Fix unknown-method error code and add a protocol version registry by @maxisbey in #2836
• Flush the stdio subprocess's coverage data before the clean-exit line by @maxisbey in #2840
• Fix 404 links in v1 README to renamed example files by @jerome3o-anthropic in #2822
• [v2] ClientSession runs on JSONRPCDispatcher; BaseSession removed by @maxisbey in #2838
• ci(conformance): pin harness to 0.2.0-alpha.3 with expected-failures baseline by @maxisbey in #2877
• ci(conformance): run server --suite draft and baseline the 2026-07-28 scenarios by @maxisbey in #2878
• Deflake the issue-1363 tests: wait for lifespan startup instead of sleeping by @maxisbey in #2879
• Widen the stdio round-trip test's termination grace and overall timeout by @maxisbey in #2880
• chore(deps): bump the github-actions group across 1 directory with 9 updates by @dependabot[bot] in #2636
• Protocol types for 2026-07-28: superset monolith, committed per-version packages, and wire-method maps by @maxisbey in #2849
• Expand site-absolute spec links in generated docstrings to full URLs by @maxisbey in #2885
• Drop stale superset-leniency note from ElicitResult.content docstring by @maxisbey in #2884

Full Changelog: v2.0.0a1...v2.0.0a2