MCP Python SDK v2.0.0rc1：API 清理与 stdio

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

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

The documentation has the full tutorial and API reference, and the migration guide covers coming from v1. Stable v2 is planned for 2026-07-28 alongside the spec release - keep pinning an exact version until then.

Highlights

API cleanup ahead of stable (breaking for beta users)

The last pre-release pass over the public surface; every item has a migration guide entry.

• Client(cache=False) is now Client(cache=None): CacheConfig() is the default and None switches the response cache off (#3164).
• Context.client_id is removed - read _meta via ctx.request_context.meta, or the authenticated client via get_access_token().client_id (#3167).
• RFC7523OAuthClientProvider and JWTParameters are removed - use ClientCredentialsOAuthProvider, PrivateKeyJWTOAuthProvider, or IdentityAssertionOAuthProvider (#3169).
• The client-credentials providers take scope=, not scopes= (#3166).
• OAuthClientProvider(timeout=...) is removed; it never bounded anything (#3165).
• message_handler receives ServerNotification | Exception only; the dead RequestResponder arm and the mcp.shared.session module are gone (#3168).
• FileResource(is_binary=...) is replaced by encoding: str | None (#3171).
• MCP_* environment variables never configured MCPServer and are no longer advertised; pydantic-settings is dropped from the runtime dependencies (#3170).
• Streamable HTTP servers reject request bodies over 4 MiB with HTTP 413; raise max_request_body_size if you accept larger messages (#3095).

Aligned with the final 2026-07-28 identity shape (#3143)

The request-side clientInfo _meta key is optional (the required pair is protocolVersion + clientCapabilities), and serverInfo moved out of the server/discover result body into every 2026-era result's _meta; client.server_info is now Implementation | None. This tracks spec change #3002 and fixes interop with servers that already omit body serverInfo.

The full 2026-07-28 revision over stdio (#3152)

A stdio (or in-memory) server now decides the protocol era from the client's opening request, so subscriptions/listen and every other 2026-07-28 feature serve over stdio, not only Streamable HTTP.

stdio servers keep handlers off the wire (#3117)

stdio_server() serves from private duplicates of stdin/stdout and points fd 0 at the null device and fd 1 at stderr while it runs, so a stray print() or a chatty child process can no longer corrupt the JSON-RPC stream. This fixes the classic print-corrupts-the-wire class (#409) and the Windows tool-call hang (#671).

Notes

• Tool results validated against an output schema are much faster: the JSON Schema validator is compiled once and cached (#3134).
• The tasks extension (SEP-2663) is not in this release, and will not be in v2.0.0.
• If you install under uv's exclude-newer cooldown: mcp pins mcp-types to the exact same version, so exempt both packages - exclude-newer-package = { mcp = false, mcp-types = false }.

What's Changed

• Add Streamable HTTP request body limits by @Kludex in #3095
• docs: document Windows stdio subprocess stdin handling by @AndreKalberer in #3079
• docs: make API reference rendering independent of page order by @maxisbey in #3107
• Pin pymdown-extensions back to 11.0 by @maxisbey in #3106
• docs: load media examples from disk instead of inline base64 by @maxisbey in #3108
• Align with spec #3002: optional clientInfo, serverInfo in result _meta by @maxisbey in #3143
• Serve the 2026-07-28 protocol over stdio: decide the era from the opening request by @maxisbey in #3152
• Isolate the stdio server's stdin and stdout from handler subprocesses by @maxisbey in #3117
• Make CacheConfig() the Client cache default and None the off switch by @maxisbey in #3164
• Remove Context.client_id by @maxisbey in #3167
• Rename scopes= to scope= on the client-credentials OAuth providers by @maxisbey in #3166
• Correct stable v2 target date to 2026-07-28 by @maxisbey in #3105
• Remove the deprecated RFC7523OAuthClientProvider by @maxisbey in #3169
• Stop advertising MCP_* env vars for MCPServer settings; drop pydantic-settings by @maxisbey in #3170
• Remove the unused timeout parameter from OAuthClientProvider by @maxisbey in #3165
• Narrow message_handler's parameter to notifications and exceptions by @maxisbey in #3168
• Replace FileResource.is_binary with an encoding field by @maxisbey in #3171
• Cache compiled output-schema validators on ClientSession by @jlowin in #3134
• Lengthen the demo signing keys in the identity-assertion examples by @maxisbey in #3180
• Repin conformance harness to the published 0.2.0-alpha.10 by @maxisbey in #3184
• Point pre-release install pins at 2.0.0rc1 by @maxisbey in #3186

New Contributors

• @AndreKalberer made their first contribution in #3079

Full Changelog: v2.0.0b2...v2.0.0rc1