The official Python SDK for Model Context Protocol servers and clients
Repo modelcontextprotocol/python-sdk, read from GitHub 1 min ago. modelcontextprotocol has not joined Take My Repo.
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:
httpx2>=2.10.0 is now required (#3600)
>=2.5.0. The new max_sse_event_size option needs it.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.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.Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None.Empty _meta and params are no longer sent (#3628)
"_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.ctx.meta is None rather than {}, and middleware sees ctx.params as None for a request without params.initialize leaves out experimental when none is configured (#3614)
"experimental": {}. server/discover already left it out.capabilities.experimental on a legacy connection should handle None.Mcp-Param-* validation looks the tool up by name (#3630)
MCPServer no longer runs tools/list for every tools/call, so middleware no longer sees that extra request.tools/list no longer affects it.An interactive OAuth login no longer counts against request timeouts (#3635)
OAuthClientProvider waits on redirect_handler and callback_handler.Client(mode="auto") settling on 2025-11-25 when the login took longer than 10 seconds.callback_handler if you need one.max_sse_event_size= on streamable_http_client and StreamableHttpParameters. The default stays 1 MiB per SSE event; raise it, or pass None, for larger tool results (#3600).MCPServer(subscriptions=False) stops serving subscriptions/listen and advertises listChanged and subscribe as false (#3626).Server(get_tool_input_schema=...) lets a low-level server supply a tool's schema for header validation without running its tools/list handler (#3630).Client.call_tool re-lists the tools and retries once after a HeaderMismatch (-32020) rejection (#3627).ctx: Context[AppState] works on prompts and resource templates, not only on tools (#3624)."structuredContent": null is checked against the output schema instead of being treated as missing (#3621).progress_callback that raises no longer fails the call on an in-process Client(server) (#3623).mode="auto", connecting to a server without server/discover now shows one ERROR span for the probe (#3629).stdio_client resolves the executable off the event loop on Windows (#3510).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:
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).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.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.Idle Streamable HTTP sessions now expire (legacy <=2025-11-25 spec( (#3395)
Client does) are not affected. Neither are stateless servers or 2026-07-28 connections.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)
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.insufficient_scope challenge is returned to the caller instead of retried.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.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).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).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.
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:
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).httpx.HTTPStatusError. If that other URL is the server you meant, use it as the endpoint URL.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)
FastMCP(..., session_idle_timeout=None, max_sessions=None).The OAuth client checks the authorization server's issuer (#3431)
issuer doesn't match the server it was fetched for is now rejected with OAuthFlowError: Authorization server metadata issuer mismatch.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.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).Full Changelog: v1.29.1...v1.30.0
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.
Full Changelog: v2.0.0...v2.0.1
Full Changelog: v2.1.0...v2.1.1
Client accepts StdioServerParameters directly: Client(StdioServerParameters(command="uv", args=["run", "server.py"])) (#3321).Image and Audio, prompt functions may return bare content blocks, and Message / UserMessage / AssistantMessage are exported from mcp.server.mcpserver (#3320).SseServerTransport and MCPServer.sse_app() take max_request_body_size, and the SSE message endpoint answers 405 to non-POST requests (#3336).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.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.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).notifications/cancelled is acknowledged with 202 instead of rejected with 400 (#3324).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).Full Changelog: v2.0.0...v2.1.0