MCP Python SDK v2.0.0b1

v2.0.0b1Pre-release
Added 14
  • First v2 beta with full support for the 2026-07-28 MCP specification
  • ServerRunner as a pure handler kernel with thin transport drivers
  • New Client that auto-discovers server protocol version with server/discover and falls back to initialize
  • Protocol types as standalone mcp_types package depending only on pydantic and typing-extensions
  • Resolver dependency injection for tools to declare typed parameter requirements
  • RFC 6570 URI templates for resource definitions with full operator set and path-security validation
Changed 1
  • FastMCP renamed to MCPServer with snake_case fields and constructor-based handler parameters
Deprecated 1
  • Roots, sampling, and logging/setLevel per SEP-2577 with advisory warnings only

First v2 beta, and the first release with full support for the 2026-07-28 MCP specification. Pre-releases are opt-in only; pip install mcp still resolves to the stable 1.x line.

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

The documentation has the full tutorial and API reference, and the migration guide covers coming from v1. Beta means the architecture is settled and changes from here should be much smaller than between alphas, but the API can still shift before stable v2, targeted for 2026-07-28 alongside the spec release - keep pinning an exact version.

What's new in v2

The whole v2 line so far (alphas included), condensed:

  • A new core. The session-centric v1 internals are replaced by a dispatcher/runner pipeline built for the stateless 2026 protocol: ServerRunner is a pure handler kernel, transports are thin drivers over it, and one endpoint serves both protocol eras side by side.
  • FastMCP is now MCPServer. The decorator API stays; the low-level Server takes handlers as constructor parameters, fields are snake_case, and traffic is validated against the negotiated spec version on the wire.
  • A new Client. Client(target, mode='auto') speaks every protocol version - it probes server/discover and falls back to initialize automatically. The target can be a URL, a stdio subprocess, a custom transport, or a server object in memory (great for tests).
  • Protocol types are a standalone package. mcp-types (imported as mcp_types) depends only on pydantic and typing-extensions, so tooling can speak MCP without the transport stack. Published in lock-step with mcp.
  • Resolver dependency injection. Tools declare what they need as typed parameters; a resolver can compute the value server-side or ask the user, with questions delivered over elicitation on 2025 sessions and multi-round-trip requests on 2026 sessions.
  • RFC 6570 URI templates. Resource templates support the full operator set - query parameters, path segments, explode modifiers - with path-security validation built in.
  • Extension APIs on both sides. Servers compose protocol extensions - including MCP Apps - through a pluggable API; clients mirror it with Client(extensions=[...]).
  • Middleware and observability. Server middleware is (ctx, call_next), and OpenTelemetry tracing ships on by default with GenAI semantic conventions.
  • Docs rebuilt on tested examples. Every snippet in the book is an executable, CI-tested file, plus a story-style examples suite and llms.txt renditions for agents.
2026-07-28 spec support

Client and server:

  • Stateless core: self-describing requests with no handshake, server/discover, scale-out on plain HTTP with no session affinity - progress and log notifications stream within the same single POST exchange.
  • Multi-round-trip requests: tools, prompts, and resources can ask for input mid-call; clients auto-resolve through their existing callbacks; on MCPServer, requestState is sealed by default (authenticated encryption) so clients cannot read or forge it.
  • Header-based routing and caching: Mcp-Method / Mcp-Name / Mcp-Param-* headers stamped by the client and validated by the server (SEP-2243), and ttlMs / cacheScope caching hints stamped by servers and honored by the client-side response cache (SEP-2549).
  • subscriptions/listen: served with a pluggable event bus (SEP-2575); the client-side listen driver follows in a later pre-release.
  • 2026-07-28 over stdio (#3038): auto-mode clients negotiate the new revision over stdio too - existing alpha clients upgrade with zero code changes.
  • Enterprise auth: SEP-990 identity assertion (ID-JAG) for enterprise IdP flows, on top of the OAuth hardening from the alphas (RFC 9207, SEP-837, SEP-2350, SEP-2352).
  • Spec deprecations: roots, sampling, and logging/setLevel are deprecated per SEP-2577 - advisory warnings only; everything keeps working for sessions on 2025-11-25 or earlier.

v2 passes the official MCP conformance suite, client and server, except the tasks suite: tasks moved to an extension in 2026-07-28, and support is in review to ship in an upcoming pre-release.

Try it, tell us what breaks
  • Coming from v1? Start with the migration guide. v1.x remains the stable line and keeps getting critical bug fixes and security patches.
  • If your package depends on mcp, add a <2 upper bound now (for example mcp>=1.27,<2) so the stable release doesn't surprise your users.
  • Feedback is the most useful thing you can give us during the beta: open a v2 issue or find us in #python-sdk-dev on the MCP Contributors Discord.
What's Changed (since previous alpha)

Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/v2.0.0a3...v2.0.0b1

View original

Upgraded? How did it go?

Discussion