v2.0.0b1

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)

• Remove comment-on-release workflow by @Kludex in #2985
• Preserve empty issuer/resource paths on AuthSettings by @Kludex in #2987
• find_invalid_x_mcp_header: never repr a non-string annotation value by @maxisbey in #2989
• Add story-style examples suite (27 stories + harness + CI) by @maxisbey in #2957
• Rebuild the docs around tested examples; shrink README.v2.md to a pitch by @maxisbey in #2978
• Add .claude/skills/test-quality and reference it from AGENTS.md by @maxisbey in #2993
• Fix docs/release follow-ups from the mcp-types package split by @maxisbey in #2977
• Mirror x-mcp-header tool arguments into Mcp-Param-* request headers (SEP-2243) by @Kludex in #2990
• Switch RFC7523OAuthClientProvider warning to MCPDeprecationWarning by @Kludex in #2996
• Make OpenTelemetry tracing the single default middleware by @Kludex in #2995
• Pin conformance harness to main@b18aa918 (merge of #371) via pkg.pr.new by @maxisbey in #3000
• Remove the dispatch-tier middleware hook by @Kludex in #2997
• Client auto-resolves InputRequiredResult via existing callbacks (SEP-2322) by @maxisbey in #2998
• Deprecate Server.init handlers for removed capabilities by @Kludex in #3002
• Support RFC 8693 token exchange for enterprise IdP flows (SEP-990) by @Kludex in #2988
• Add SSE response mode to the 2026 streamable-HTTP server entry by @maxisbey in #3001
• feat: RFC 6570 URI templates with operator-aware security by @maxisbey in #2356
• Add docs, tested examples, and a story for SEP-990 identity assertion by @maxisbey in #3004
• Re-vendor 2026-07-28 schema at spec ead35b59 (SubscriptionsListenResult) by @maxisbey in #3006
• Wire SEP-990 enterprise-managed-authorization conformance fixture by @maxisbey in #3007
• Add a pluggable server extension API with MCP Apps by @Kludex in #3003
• Add resolver dependency injection for MCPServer tools by @Kludex in #2969
• Promote the v2 README to README.md ahead of the first v2 beta by @maxisbey in #3014
• docs: convert bold cross-references into links, link SEP and RFC mentions by @maxisbey in #3017
• Drive resolver elicitation over the 2026-07-28 input_required flow by @Kludex in #2986
• Add cache_hints constructor map for SEP-2549 caching hints by @maxisbey in #3015
• Consult request_state only for the question a resolver is asking by @maxisbey in #3019
• Pass InputRequiredResult through the MCPServer prompt and resource pipelines by @maxisbey in #3020
• docs: publish llms.txt and markdown renditions of the docs by @maxisbey in #3024
• Add a client-side response cache honoring SEP-2549 caching hints by @maxisbey in #3023
• Surface skipped conformance scenarios as baselined known failures by @maxisbey in #3030
• Add Cloudflare Pages docs preview with /preview-docs slash command by @localden in #3028
• Require integrity protection for MRTR requestState by @maxisbey in #3032
• Add a client extension API by @maxisbey in #3034
• Validate Mcp-Param-* headers server-side on the 2026-07-28 HTTP path (SEP-2243) by @maxisbey in #3033
• Serve subscriptions/listen with a pluggable event bus (SEP-2575) by @maxisbey in #3035
• Add v2 feedback issue template by @maxisbey in #3037
• Document pydantic.ValidationError in client Raises sections by @maxisbey in #3036
• Serve the 2026-07-28 era over stdio and other stream-pair transports by @maxisbey in #3038
• Point pre-release install pins at 2.0.0b1 by @maxisbey in #3039

Full Changelog: v2.0.0a3...v2.0.0b1