MCP Python SDK Updates & Release Notes

pip install -U mcp. Docs: https://py.sdk.modelcontextprotocol.io/

Behaviour changes

HTTP client redirects are only followed within the endpoint's origin (#3397)

Client("https://..."), streamable_http_client and sse_client follow a redirect only if it stays on the same scheme, host and port (or upgrades http to https on the same host).

A redirect anywhere else is not followed: the call fails with MCPError and the session stays usable (an SSE connect fails with httpx2.HTTPStatusError). If that other URL is the server you meant, use it as the endpoint URL.

The follow_redirects setting on an httpx2.AsyncClient you pass in is no longer used for MCP requests, so you don't need it for the trailing-slash redirect any more.

The OAuth providers apply the same rule to their own requests.

Idle Streamable HTTP sessions now expire (legacy <=2025-11-25 spec( (#3395)

A stateful session with nothing in flight for 30 minutes is closed. The client's next request gets a 404 and it has to initialize again.

Clients that keep the GET stream open (the SDK's Client does) are not affected. Neither are stateless servers or 2026-07-28 connections.

A server also holds at most 10 000 sessions at once; beyond that, new sessions get a 503.

To turn either off: mcp.run(transport="streamable-http", session_idle_timeout=None, max_sessions=None) (also on streamable_http_app() and run_streamable_http_async()).

The OAuth client checks the authorization server's issuer on the legacy path too (#3398)

For servers without protected resource metadata, authorization server metadata whose issuer isn't the server's own origin is now rejected with OAuthFlowError: Authorization server metadata issuer mismatch. The protected-resource-metadata path has done this since 2.0.

A 403 that isn't an insufficient_scope challenge is returned to the caller instead of retried.

If protected resource metadata can't be fetched because of a 5xx/429, the flow now stops instead of falling back to the legacy endpoints.

Two new MCPDeprecationWarnings (#3435, #3447)

ClientCredentialsOAuthProvider / PrivateKeyJWTOAuthProvider without issuer=. Pass your authorization server's issuer URL; 3.0 will require it.

AuthSettings with resource_server_url set but validate_token_resource unset. Set it to True or False; 3.0 defaults it to True.

Both keep working as before in 2.x; this mostly matters if your tests turn warnings into errors.

New

AuthSettings.validate_token_resource: only accept tokens your TokenVerifier reports as issued for this server (#3447).

issuer= on ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider (#3398).

session_idle_timeout= and max_sessions= on the Streamable HTTP server entry points (#3395).

Fixes

A client DELETE frees its session immediately, and a refused opening request no longer leaves a session behind (#2455, #3228, #3300).

$refs in a tool's outputSchema resolve within that schema only; an unresolvable one surfaces as RuntimeError: Invalid schema for tool ... (#3394).

Known gaps

The tasks extension (SEP-2663), DPoP (SEP-1932) and the jwt-bearer grant are not implemented yet; https://github.com/modelcontextprotocol/python-sdk/blob/main/ROADMAP.md tracks them.

What's Changed

Gate draft PRs too and rewrite the auto-close comment by @maxisbey in #3378

Resolve tool output-schema references within the schema document only by @maxisbey in #3394

Expire idle Streamable HTTP sessions by default and cap concurrent sessions by @maxisbey in #3395

Validate the authorization server metadata issuer on every discovery path by @maxisbey in #3398

Deprecate constructing the pre-provisioned OAuth clients without an issuer by @maxisbey in #3435

Exercise the SEP-2575 stateless probes and SEP-2243 resource/prompt headers in the conformance fixtures by @maxisbey in #3442

Bump the github-actions group with 6 updates by @dependabot[bot] in #3424

Move the docs-preview workflow scripts out of the YAML into .github/scripts by @maxisbey in #3446

Skip automatic docs previews for fork PRs and drop the setup-uv retry steps by @maxisbey in #3445

Follow redirects only within the MCP endpoint's origin by @maxisbey in #3397

Bump pymdown-extensions from 11.0 to 11.0.1 by @dependabot[bot] in #3285

Bump the locked versions of eight dev and test dependencies by @maxisbey in #3449

Keep following a relative redirect when the endpoint URL carries userinfo by @maxisbey in #3450

Add AuthSettings.validate_token_resource to check a bearer token's resource by @maxisbey in #3447

docs: stop presenting the in-memory client as the way to connect by @maxisbey in #3443

docs: ask for AI disclosure on comments too by @maxisbey in #3459

docs: refresh translations, and translate pages in parallel by @maxisbey in #3458

Replace RootModel wrappers with type aliases and TypeAdapter validation by @Kludex in #3470

Full Changelog: v2.1.1...v2.2.0

Maintenance release of the 1.x line. 2.x is the current line; 1.x docs are at https://py.sdk.modelcontextprotocol.io/v1/.

A few defaults changed in this release. If you run a server or client on 1.x, skim these first:

Behaviour changes

HTTP client redirects are only followed within the endpoint's origin (#3448)

streamable_http_client and sse_client follow a redirect only if it stays on the same scheme, host and port (or upgrades http to https on the same host).

A redirect anywhere else now fails the request with httpx.HTTPStatusError. If that other URL is the server you meant, use it as the endpoint URL.

The follow_redirects setting on an httpx.AsyncClient you pass in is no longer used for MCP requests, so you don't need it for the trailing-slash redirect any more.

OAuthClientProvider applies the same rule to its own requests.

Idle Streamable HTTP sessions now expire (#3426)

A stateful session with nothing in flight for 30 minutes is closed. The client's next request gets a 404 and it has to initialize again.

Clients that keep the GET stream open (the SDK's client does) are not affected.

A server also holds at most 10 000 sessions at once; beyond that, new sessions get a 503.

To turn either off: FastMCP(..., session_idle_timeout=None, max_sessions=None).

The OAuth client checks the authorization server's issuer (#3431)

Authorization server metadata whose issuer doesn't match the server it was fetched for is now rejected with OAuthFlowError: Authorization server metadata issuer mismatch.

Client registrations are now remembered per issuer; if the server later points at a different authorization server, the client registers again.

If protected resource metadata can't be fetched because of a 5xx/429, the flow now stops instead of falling back to the legacy endpoints.

Two new DeprecationWarnings (#3431, #3451)

ClientCredentialsOAuthProvider / PrivateKeyJWTOAuthProvider without issuer=. Pass your authorization server's issuer URL.

AuthSettings with resource_server_url set but validate_token_resource unset. Set it to True or False.

Both keep working as before in 1.x; this mostly matters if your tests turn warnings into errors.

New

AuthSettings.validate_token_resource: only accept tokens your TokenVerifier reports as issued for this server (#3451).

issuer= on ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider (#3431).

session_idle_timeout= and max_sessions= on FastMCP (#3426).

What's Changed

• [v1.x] Resolve tool output-schema references within the schema document only by @maxisbey in #3396
• [v1.x] Expire idle Streamable HTTP sessions by default and cap concurrent sessions by @maxisbey in #3426
• [v1.x] Validate the authorization server metadata issuer on every discovery path by @maxisbey in #3431
• [v1.x] Follow redirects only within the MCP endpoint's origin by @maxisbey in #3448
• [v1.x] Add AuthSettings.validate_token_resource to check a bearer token's resource by @maxisbey in #3451

Full Changelog: v1.29.1...v1.30.0

Highlights

Client accepts StdioServerParameters directly: Client(StdioServerParameters(command="uv", args=["run", "server.py"])) (#3321).

Prompt messages accept Image and Audio, prompt functions may return bare content blocks, and Message / UserMessage / AssistantMessage are exported from mcp.server.mcpserver (#3320).

The 4 MiB request body limit now also covers the SSE transport and the OAuth endpoints; SseServerTransport and MCPServer.sse_app() take max_request_body_size, and the SSE message endpoint answers 405 to non-POST requests (#3336).

Behaviour changes to be aware of

Handler exceptions (#3314): an unexpected exception from a tool, resource or prompt handler is logged once at ERROR with its traceback, and the client now sees only Error executing tool <name> (or the resource/prompt equivalent) rather than the exception text. Raise ToolError / ResourceError when the message is meant for the model; those still reach the client and are logged at INFO without a traceback.

Content-block return annotations (#3320): a tool annotated to return TextContent, EmbeddedResource, Image, Audio, or lists/unions of them no longer advertises outputSchema or returns structuredContent; its content is unchanged. Pass structured_output=True to keep the previous shape.

Fixes

TypedDict tool results: NotRequired keys are omitted instead of serialized as null, and registration no longer fails on Python 3.10 (#3224, #3227); recursive return types get an object-rooted outputSchema that pre-2026 clients accept (#3337).

2026-07-28 over HTTP: a POSTed notification such as notifications/cancelled is acknowledged with 202 instead of rejected with 400 (#3324).

Pre-2026 sessions ignore cache-hint fields from later revisions instead of failing list_tools() (#3223), and accept boolean sub-schemas in tool schema properties (#3353).

mcp install reads and preserves a Claude Desktop config containing non-ASCII text on any Windows code page (#3296).

What's Changed

Retire wording tied to pre-2.0 milestones by @maxisbey in #3211

Describe the maintenance line without hardcoding 1.28 by @maxisbey in #3212

Ask which release line a bug report is on by @maxisbey in #3213

Link the released 2026-07-28 spec and point migrators at /v1/ by @maxisbey in #3214

Bump conformance harness to 0.2.0-alpha.11 by @maxisbey in #3282

Read UTF-8 test fixtures with explicit encoding by @ShuQingDollarVoyager in #3245

Pin each conformance leg to a spec-revision wire by @maxisbey in #3304

docs: publish translated docs in twelve languages and the tool that maintains them by @maxisbey in #3280

Pin text I/O to UTF-8 and fail CI on locale-dependent reads/writes by @maxisbey in #3296

docs: lead the README client example with a URL, not the server object by @maxisbey in #3315

Publish versioning, roadmap, and dependency policies for v2 by @maxisbey in #3215

Drop later-revision cache-hint fields on pre-2026 sessions by @maxisbey in #3223

Stop framing breaking changes as a workflow in AGENTS.md by @maxisbey in #3286

MCPServer: content-block returns are unstructured, prompt messages take Image/Audio by @maxisbey in #3320

Let Client take StdioServerParameters directly by @maxisbey in #3321

Gate external PRs on an assigned, linked issue by @maxisbey in #3291

docs: cover the remaining Tier 1 audit items by @maxisbey in #3325

Acknowledge notification POSTs with 202 on the 2026-07-28 HTTP entry by @maxisbey in #3326

Shorten stdio test comments by @Kludex in #3329

Hand TypedDict tool results to pydantic natively by @maxisbey in #3331

Apply the request body limit to the SSE and OAuth endpoints by @maxisbey in #3336

Accept boolean sub-schemas in 2025-11-25 tool schema properties by @pja-ant in #3354

Log MCPServer handler exceptions by kind and keep crash details off the wire by @maxisbey in #3314

Give recursive tool return types an object-rooted output schema by @maxisbey in #3376

docs: refresh translations for recent English changes by @maxisbey in #3379

Build releases with the pinned hatchling and a publish action that accepts Metadata 2.5 by @maxisbey in #3380

New Contributors

@ShuQingDollarVoyager made their first contribution in #3245

Full Changelog: v2.0.0...v2.1.0

MCP Python SDK v2 Stable Release

This is v2.0.0, the stable v2 release of the MCP Python SDK. It supports the 2026-07-28 revision of the Model Context Protocol and serves every earlier revision from the same server. pip install mcp now installs 2.x.

pip install "mcp[cli]"
# or
uv add "mcp[cli]"

Documentation Rewrite

The documentation has the full tutorial and API reference. Coming from v1? What's new in v2 is the tour of what changed and why, and the migration guide lists every breaking change with before-and-after code.

V1 Maintenance mode

v1.x is in maintenance mode and will only receive security fixes from now on The 1.x line lives on the v1.x branch, continues to receive critical bug fixes and security patches, and is documented at https://py.sdk.modelcontextprotocol.io/v1/. If your project is not ready to migrate, keep a <2 upper bound on your requirement (for example mcp>=1.28,<2).

Highlights

One SDK, both protocol eras

v2 speaks the 2026-07-28 revision (stateless requests with no handshake, server/discover, subscriptions/listen, multi-round-trip requests) and still serves every 2025-era client from the same MCPServer, over Streamable HTTP and stdio, with nothing to configure. Client(target) negotiates the version automatically.

FastMCP is now MCPServer, and there is a first-class Client

The decorator API is unchanged; the low-level Server is rebuilt around a shared dispatcher engine, and one Client object replaces v1's transport-plus-ClientSession-plus-initialize() layering. It connects to a URL, a stdio subprocess, a custom transport, or straight to a server object in memory for tests.

Multi-round-trip requests and resolver dependency injection

At 2026-07-28 the server can no longer call the client, so tools return the question instead. A Resolve(fn) parameter is filled by your function invisibly to the model and can put a question to the user; one tool body serves both eras.

Extension APIs, OpenTelemetry, and a standalone types package

Servers and clients compose protocol extensions through pluggable extension APIs (MCP Apps built in); OpenTelemetry tracing ships on by default; every protocol type is its own package, mcp-types (imported as mcp_types), published in lock-step with mcp.

Hardened stdio and auth

stdio servers keep handler subprocesses and stray prints off the wire, and stdout is diverted to stderr while serving. OAuth adds RFC 9207 issuer validation, the SEP-990 identity-assertion flow, and the client-credentials extension.

Coming from a v2 pre-release

Since the last release candidate: the per-version wire packages are private (mcp_types.v*), mcp.types is a permanent alias for mcp_types, the auth registration request model is split from the registered-client record, cancelled requests are no longer answered, and log notifications are gated on the per-request log-level opt-in at 2026-07-28. Since the betas: Client(cache=False) is now cache=None with CacheConfig() the default; Context.client_id, RFC7523OAuthClientProvider, and OAuthClientProvider(timeout=) are removed; the client-credentials providers take scope=; message_handler receives notifications and exceptions only; FileResource(is_binary=) becomes encoding; MCP* env vars are gone with pydantic-settings; Streamable HTTP servers reject bodies over 4 MiB with HTTP 413. The migration guide covers all of it.

Known gaps

The tasks extension (SEP-2663) is not part of this release. On the client, the DPoP proof binding (SEP-1932) and the workload-identity jwt-bearer grant are not implemented; both are additive and can land in 2.x.

Feedback

Something rough, confusing, or broken? Open an issue or find us in #python-sdk-dev on the MCP Contributors Discord.

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

What's Changed

[v1.x] Route Context.report_progress() to the originating request stream by @maxisbey in #2994

[v1.x] docs: publish llms.txt and markdown renditions of the docs by @maxisbey in #3029

[v1.x] docs: pin mkdocs<2 by @maxisbey in #3074

[v1.x] Add Streamable HTTP request body limits by @Kludex in #3101

[v1.x] fix: reject trailing newline in tool-name validation by @maxisbey in #3086

[v1.x] ci: pick the docs toolchain per worktree in build-docs.sh by @maxisbey in #3082

[v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line by @maxisbey in #3177

Full Changelog: v1.28.1...v1.29.0

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

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

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

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

Highlights

• httpx is replaced by httpx2 (#2972)

The SDK's HTTP stack now runs on httpx2 (>=2.5.0), the next-generation httpx fork with SSE support built in, replacing httpx + httpx-sse. Most code needs no changes; if you pass your own http_client into a transport, change the import to httpx2. Runtime behavior that changes:

• TLS verification uses the operating system trust store (via truststore) instead of certifi's bundle. SSL_CERT_FILE / SSL_CERT_DIR are honored first.

• Loggers are renamed: httpx -> httpx2, httpcore.* -> httpcore2.* - update logging filters that match on those names.

• SSE GET streams send Accept: application/json, text/event-stream (previously exactly text/event-stream).

• Client-side subscriptions/listen (#3047)

The client half of subscriptions/listen (SEP-2575), promised in the b1 notes: one context manager, async for consumption, typed events.

async with client.listen(tools_list_changed=True, resource_subscriptions=["note://todo"]) as sub:
print(sub.honored) # the subset the server agreed to deliver
async for event in sub:
match event:
case ToolsListChanged():
tools = await client.list_tools()
case ResourceUpdated(uri=uri):
body = await client.read_resource(uri)

Entering waits for the server's acknowledgment, so sub.honored is always populated and pre-ack failures raise instead of degrading silently.

• Request cancellation works on the 2026 transports (#3046)

Cancelling or timing out a client request now actually stops it: over streamable HTTP the request's own POST/SSE stream is closed (the spec's cancellation signal), and over stdio the client sends notifications/cancelled. Callers can also supply the request id for a call - the seam the listen driver builds on.

• Resolvers can sample and list roots (#3049)

Resolver dependency injection now covers all three multi-round-trip request kinds (SEP-2322): a dependency can return Sample(...) or ListRoots() in addition to Elicit(...), so a tool can ask the client's LLM or fetch its roots mid-call, on both protocol eras.

Notes

• Tool-name validation now rejects names with a trailing newline (#3076).
• The tasks extension is still in review and will ship in a later pre-release.
• 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

• De-flake conformance CI: solo re-verification, spawn-storm reduction, result artifacts by @maxisbey in #3043
• Harden the dual-era stream loop's era-lock and rejection semantics by @maxisbey in #3040
• docs: restructure into topical sections and add the four most-asked-for pages by @maxisbey in #3044
• docs: add a "What's new in v2" page by @maxisbey in #3054
• docs: modernize the site theme by @maxisbey in #3057
• docs: restructure the migration guide around topical groups with a navigation layer by @maxisbey in #3058
• Make client-side cancellation work over the 2026 transports by @maxisbey in #3046
• Extend resolver DI to sampling and roots requests by @maxisbey in #3049
• Share one event loop per test module to stop Windows socketpair churn by @maxisbey in #3070
• docs: pin mkdocs<2 and silence the mkdocs-material advisory banner in CI by @maxisbey in #3072
• Add the client-side subscriptions/listen driver by @maxisbey in #3047
• Gate the test matrix and retry setup-uv's flaky manifest fetch by @maxisbey in #3080
• ci: pick the docs-preview toolchain from the PR checkout by @maxisbey in #3081
• docs: replace MkDocs with Zensical by @Kludex in #3073
• fix: reject trailing newline in tool-name validation by @Otis0408 in #3076
• Replace httpx and httpx-sse with httpx2 by @Kludex in #2972

New Contributors

• @Otis0408 made their first contribution in #3076

Full Changelog: v2.0.0b1...v2.0.0b2

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

Third v2 alpha.

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

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

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

Warning

The public API is likely to change between alpha releases, and ideally less-so between beta releases.

Highlights

2026-07-28 stateless protocol is now negotiable end to end (#2928, #2950)

The 2026-07-28 spec revision drops the initialize handshake on streamable HTTP: each POST is self-describing (protocol version, client info, and capabilities ride in params._meta) and the server replies with a single JSON-RPC response. Both sides of that path are now wired up.

Server side: ServerRunner is now a pure handler kernel composed by three drivers (serve_one, serve_connection, serve_loop). A new Connection object owns per-peer state with two factories - from_envelope for the per-request stateless path and for_loop for handshake-driven connections - so protocol_version is always set and the old stateless: bool flag is gone from ServerRunner, ServerSession, and Server.run(). The streamable-HTTP session manager routes by header: known handshake versions go to the legacy transport; everything else hits a new per-POST entry that classifies, builds a Connection.from_envelope, and drives serve_one. server/discover is auto-derived from registered handlers, and lifespan is entered once at manager startup in both modes.

Client side: ClientSession gains .discover() and .adopt() alongside .initialize(), each of which installs an outbound stamp closure at connect time so the send path has no era branch. Client gains mode='legacy'|'auto'|<version> and prior_discover=; mode='auto' probes server/discover and falls back to initialize on -32601 or timeout. The streamable-HTTP transport is now version-agnostic (per-message headers arrive via CallOptions), and an in-process modern_on_request driver lets Client(server, mode='auto') run the stateless path against an in-memory server.

LATEST_PROTOCOL_VERSION is now "2026-07-28". SUPPORTED_PROTOCOL_VERSIONS is deprecated in favour of HANDSHAKE_PROTOCOL_VERSIONS and MODERN_PROTOCOL_VERSIONS.

Protocol types split into a standalone mcp-types package (#2973)

The wire types now ship as a separate mcp-types distribution (imported as mcp_types) that depends only on pydantic and typing-extensions. Tooling and lightweight clients can serialize and validate MCP traffic without pulling in httpx, starlette, uvicorn, or the rest of the transport stack.

mcp.types and mcp.shared.version are removed; import from mcp_types and mcp_types.version instead. The top-level from mcp import Tool re-exports are unchanged. The two packages are version-locked and published together from the same tag.

Multi-round tool calls: InputRequiredResult plumbed through both sides (#2967, #2968, #2974)

The lowlevel Server on_* return types are widened to admit InputRequiredResult, and a subscriptions/listen handler slot is added. On the client, ClientSession.call_tool gains input_responses= and request_state= retry kwargs and returns CallToolResult | InputRequiredResult; Client.call_tool and ClientSessionGroup.call_tool are overloaded on a new allow_input_required flag so existing callers keep their CallToolResult return type. ClientSession.send_request now accepts a TypeAdapter for union result parsing.

ServerMiddleware reshaped to (ctx, call_next) and OpenTelemetryMiddleware added (#2941, #2970)

ServerMiddleware.call goes from (ctx, method, params, call_next) to (ctx, call_next); method and raw params now live on ServerRequestContext, and call_next(ctx) lets middleware rewrite the inbound message via replace(ctx, params=...) before the handler runs. A new context-tier OpenTelemetryMiddleware spans both requests and notifications and sets the OpenTelemetry GenAI semantic-convention attributes.

OAuth client conformance: RFC 9207, SEP-837, SEP-2350, SEP-2352 (#2921, #2930, #2931, #2933)

The OAuth client now validates the iss authorization-response parameter (RFC 9207), sends application_type during Dynamic Client Registration (SEP-837), unions previously requested scopes on step-up re-authorization (SEP-2350), and binds client credentials to the authorization server that issued them (SEP-2352). #2936 and #2946 harden the edge cases (refresh-token retention on non-rotating refresh, same-origin issuer binding).

Roots, sampling, and logging methods deprecated per SEP-2577 (#2926)

The user-facing methods for roots, sampling, and logging/setLevel are now marked with typing_extensions.deprecated. The deprecation is advisory only - capability negotiation and wire behaviour are unchanged, and everything keeps working for sessions negotiating 2025-11-25 or earlier.

What's Changed

• Pass a list to parametrize in test_docs_examples (pytest 9.1.0 compat) by @maxisbey in #2890
• docs: add AI-assisted contribution policy to CONTRIBUTING.md by @maxisbey in #2887
• Resolve protocol version per request and expose it as ctx.protocol_version by @maxisbey in #2886
• tests/interaction: era-axis machinery for the requirements manifest by @maxisbey in #2909
• ci(conformance): add 2026-07-28 carried-forward leg + bump harness to 0.2.0-alpha.4 by @maxisbey in #2911
• Re-vendor 2026-07-28 schema and absorb spec #2907 error-code renumber by @maxisbey in #2912
• Relax monolith ElicitRequestURLParams.elicitation_id for 2026-07-28 by @maxisbey in #2913
• First end-to-end 2026-07-28 stateless tools/call (experimental entry + ClientSession pin) by @maxisbey in #2917
• Add uv ecosystem to dependabot and drop weekly lockfile workflow by @Kludex in #2919
• Return -32602 for resource not found (SEP-2164) by @Kludex in #2920
• fix: correct MCPServer call_tool result type by @fengjikui in #2816
• Ignore pre-2026 protocol_version pins at the StreamableHTTP transport by @maxisbey in #2923
• Preserve empty URL paths on OAuth metadata models by @Kludex in #2925
• Validate the iss authorization-response parameter (RFC 9207 / SEP-2468) by @Kludex in #2921
• ci(conformance): bump harness to 0.2.0-alpha.5 preview by @maxisbey in #2927
• Document redirect_uri wire-format change in OAuth migration note by @Kludex in #2929
• Send application_type during Dynamic Client Registration (SEP-837) by @Kludex in #2930
• Pass json-schema-ref-no-deref conformance scenario (SEP-2106) by @Kludex in #2924
• Deprecate roots, sampling, and logging methods per SEP-2577 by @Kludex in #2926
• Union previously requested scopes on step-up re-authorization (SEP-2350) by @Kludex in #2931
• Move scope step-up test to top-level function by @Kludex in #2932
• Bind client credentials to their authorization server (SEP-2352) by @Kludex in #2933
• Server-side 2026-07-28 stateless support: classifier, driver split, server/discover by @maxisbey in #2928
• OAuth client: harden SEP-2352/SEP-2350 edge cases; fix conformance comment by @maxisbey in #2936
• Slim ServerMiddleware to (ctx, call_next) and add OpenTelemetryMiddleware by @Kludex in #2941
• OAuth client: keep refresh_token on non-rotating refresh; restore same-origin issuer binding by @maxisbey in #2946
• Buffer per-request StreamableHTTP streams to avoid serial-router head-of-line block by @maxisbey in #2934
• lowlevel Server: widen on_* return types for InputRequiredResult; add subscriptions/listen slot by @maxisbey in #2967
• Client-side 2026-07-28 support: .discover()/.adopt() + Client(mode=); request-metadata green by @maxisbey in #2950
• Add GenAI semantic-convention attributes to OpenTelemetryMiddleware by @Kludex in #2970
• Stop flagging snake_case is_error results as tool errors in OTel span by @Kludex in #2971
• Client call_tool: input_responses/request_state retry params; InputRequiredResult via allow_input_required by @maxisbey in #2968
• Split protocol types into a standalone mcp-types package by @Kludex in #2973
• Set Development Status classifier to Production/Stable by @maxisbey in #2975
• Conformance burn-down: server-side InputRequiredResult, Mcp-Method/Name validation, x-mcp-header filter (14 scenarios → green) by @maxisbey in #2974

New Contributors

• @fengjikui made their first contribution in #2816

Full Changelog: v2.0.0a2...v2.0.0a3

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

Deprecations

Two API surfaces now emit DeprecationWarning ahead of their removal in v2. Nothing is removed in 1.x, and the warnings fire only when the deprecated API is called - importing the modules stays silent.

WebSocket transport - mcp.client.websocket.websocket_client and mcp.server.websocket.websocket_server. WebSocket was never part of the MCP specification; use the streamable HTTP transport instead. The TypeScript SDK has likewise removed its WebSocket client for v2 (modelcontextprotocol/typescript-sdk#1783).

Experimental tasks API - ClientSession.experimental, Server.experimental, ServerSession.experimental, and the experimental_task_handlers= kwarg on ClientSession. Tasks (SEP-1686) were removed from the MCP specification and are expected to return as a separate MCP extension.

If your test suite runs with filterwarnings = ["error"] and exercises these paths, add a scoped ignore such as ignore:The experimental tasks API is deprecated:DeprecationWarning or ignore:The WebSocket .* transport is deprecated:DeprecationWarning.

See #2828 for full details.

What's Changed

• [v1.x] Support Python 3.14 by @maxisbey in #2769
• fix: omit null optional fields from task result payloads by @liuzemei in #2809
• [v1.x] Deprecate the WebSocket transport and the experimental tasks entry points by @maxisbey in #2828
• [v1.x] Add a v2 status banner to the README by @maxisbey in #2835
• [v1.x] Deflake the child process cleanup tests by @maxisbey in #2839

New Contributors

@liuzemei made their first contribution in #2809

Full Changelog: v1.27.2...v1.28.0