Python SDK Updates & Release Notes

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

Mostly fixes, plus three new options. A few things behave differently, so skim these first:

Behaviour changes

httpx2>=2.10.0 is now required (#3600)

• It was >=2.5.0. The new max_sse_event_size option needs it.
• Nothing to do unless you pin httpx2 below 2.10.

A tool with an invalid x-mcp-header annotation fails at registration (#3620)

• @mcp.tool(), add_tool and Tool.from_function raise InvalidSignature, naming the tool and the problem.
• Until now the server started, and 2026-07-28 clients silently dropped the tool from their listing.
• Refused: anything other than a plain str, int or bool parameter (so also str | None, float, lists and enums), a header name that isn't a valid token, and two names that differ only by case.
• For an optional header parameter, give the schema directly: Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None.

Empty _meta and params are no longer sent (#3628)

• On 2025-11-25 and earlier connections, 2.x sent "_meta": {} on every request. Some servers reject that. It is now left out, as in v1.
• ping and list requests without a cursor go out with no params member.
• On the receiving side ctx.meta is None rather than {}, and middleware sees ctx.params as None for a request without params.
• 2026-07-28 connections are unchanged. …

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

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

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. …

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) …

One off backport of the FastMCP import warning for 2.0.x, this is due to a lot of people running into this error and making issues on other repos about it. Ideally either pin mcp<2 or upgrade to 2.

What's Changed

• [v2.0.x] Point imports of mcp.server.fastmcp at the migration guide by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3393

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

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 …

What's Changed

• [v1.x] Complete the FastMCP Settings model at import time by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3352
• [v1.x] Apply the request body limit to the SSE and OAuth endpoints by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3344
• [v1.x] Give recursive tool return types an object-rooted output schema by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3377

Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/v1.29.0...v1.29.1

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 …

What's Changed

• [v1.x] Route Context.report_progress() to the originating request stream by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/2994
• [v1.x] docs: publish llms.txt and markdown renditions of the docs by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3029
• [v1.x] docs: pin mkdocs<2 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3074
• [v1.x] Add Streamable HTTP request body limits by @Kludex in https://github.com/modelcontextprotocol/python-sdk/pull/3101
• [v1.x] fix: reject trailing newline in tool-name validation by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3086
• [v1.x] ci: pick the docs toolchain per worktree in build-docs.sh by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3082
• [v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3177

Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/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). …

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.