v2.3.02026-10-02
MCP Python SDK 这版以修复为主,另加三个新选项,但有几处行为变化,升级前值得先过一眼。
依赖上,httpx2 最低要求提到 2.10.0,因为新增的 maxsseevent_size 需要它;若你锁了更低版本需同步调整。带 x-mcp-header 注解的工具现在在注册阶段就校验参数:非 str/int/bool 类型(含 str | None、float、列表、枚举)、非法请求头名、仅大小写不同的重名,都会直接抛 InvalidSignature 并点名问题,不再让服务器带病启动、工具被客户端静默丢弃。可选请求头参数需直接给出 schema。
协议层面更干净了:空的 meta 和 params 不再随请求发送,兼容旧连接时避免被部分服务器拒收;接收侧 ctx.meta、ctx.params 相应变为 None。initialize 在未配置时不再带 "experimental": {},读取 capabilities.experimental 的客户端代码要能处理 None。Mcp-Param- 校验改为按名查表,tools/call 不再额外触发 tools/list,中间件对列表的过滤或改写也不再影响校验结果。交互式 OAuth 登录期间请求超时会暂停,修复了登录耗时较长时 Client(mode="auto") 误判为 2025-11-25 的问题。
新增能力:streamablehttpclient 与 StreamableHttpParameters 支持 maxsseeventsize=(默认仍为每事件 1 MiB,可调大或传 None);MCPServer(subscriptions=False) 可关闭订阅服务并如实宣告能力;Server(gettoolinputschema=...) 让底层服务器在不跑 tools/list 的前提下提供校验用 schema;Client.call_tool 遇到 HeaderMismatch(-32020)会重新拉取工具列表并重试一次。
修复方面:ctx: Context[AppState] 现可用于 prompts 和资源模板;显式 "structuredContent": null 按输出 schema 校验而非视为缺失;进程内 Client(server) 中 progresscallback 抛错不再导致调用失败;OpenTelemetry 会记录 JSON-RPC 错误响应,mode="auto" 探测无 server/discover 的服务器时显示单个 ERROR span;Windows 上 stdioclient 的可执行文件解析移出事件循环。文档新增取消与请求头参数两页及中间件教程,十二种语言译文同步更新。
v2.2.02026-09-07
MCP Python SDK 更新:默认行为有几处调整,2.x 用户升级前建议先过一遍。HTTP 客户端现在只跟随同源重定向,跨源跳转会直接报 MCPError,会话仍可继续使用;若目标就是那个地址,直接把它写进端点 URL 即可。Streamable HTTP 的闲置会话 30 分钟后自动关闭,下次请求会收到 404 并需重新初始化,同时单服务器最多保留 1 万个会话,超出返回 503——SDK 自带的 Client 因保持 GET 流常开而不受影响,也可用 sessionidletimeout=None、maxsessions=None 关掉。OAuth 侧,旧路径也开始校验授权服务器元数据的 issuer,不匹配会抛 OAuthFlowError;另新增两条 MCPDeprecationWarning,提醒 3.0 将强制要求 issuer= 和 validatetoken_resource。修复方面,客户端 DELETE 会立即释放会话,工具 outputSchema 中的 $ref 只在本 schema 内解析。tasks 扩展、DPoP 与 jwt-bearer 授权仍未实现。
v1.30.02026-09-07
MCP Python SDK 1.30.0 是 1.x 分支的维护版本,2.x 才是当前主线。这版改了几处默认行为,1.x 用户升级前建议先过一遍:
HTTP 客户端的重定向现在只允许留在端点同源范围内(scheme、host、port 一致,或 http 升级到 https)。跳到别处会直接抛 httpx.HTTPStatusError,若目标才是真正的服务器,请直接把它写成端点 URL。streamablehttpclient、sseclient 与 OAuthClientProvider 均遵循此规则,你自行传入的 followredirects 对 MCP 请求不再生效。
有状态的 Streamable HTTP 会话空闲 30 分钟后会被关闭,下次请求收到 404 需重新初始化;保持 GET 流打开的客户端不受影响。服务器同时最多保留 10000 个会话,超出返回 503。两者均可关闭:FastMCP(..., sessionidletimeout=None, max_sessions=None)。
OAuth 客户端开始校验授权服务器元数据的 issuer,不匹配即报错;客户端注册改为按 issuer 记忆,受保护资源元数据拉取遇 5xx/429 时流程直接中止,不再回退到旧端点。另有两处新弃用警告:ClientCredentialsOAuthProvider、PrivateKeyJWTOAuthProvider 未传 issuer=,以及 AuthSettings 设了 resourceserverurl 却未设 validatetokenresource,1.x 下仍可正常运行,但把警告当错误的测试会受影响。
新增 AuthSettings.validatetokenresource,只接受签发给本服务器的令牌。
v2.0.12026-08-26
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
v2.1.12026-08-25
What's Changed
* Point imports of mcp.server.fastmcp at the migration guide by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3388
Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/v2.1.0...v2.1.1
v2.1.02026-08-24
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.sseapp() take maxrequestbodysize, 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 https://github.com/modelcontextprotocol/python-sdk/pull/3211
* Describe the maintenance line without hardcoding 1.28 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3212
* Ask which release line a bug report is on by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3213
* Link the released 2026-07-28 spec and point migrators at /v1/ by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3214
* Bump conformance harness to 0.2.0-alpha.11 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3282
* Read UTF-8 test fixtures with explicit encoding by @ShuQingDollarVoyager in https://github.com/modelcontextprotocol/python-sdk/pull/3245
* Pin each conformance leg to a spec-revision wire by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3304
* docs: publish translated docs in twelve languages and the tool that maintains them by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3280
* Pin text I/O to UTF-8 and fail CI on locale-dependent reads/writes by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3296
* docs: lead the README client example with a URL, not the server object by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3315
* Publish versioning, roadmap, and dependency policies for v2 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3215
* Drop later-revision cache-hint fields on pre-2026 sessions by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3223
* Stop framing breaking changes as a workflow in AGENTS.md by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3286
* MCPServer: content-block returns are unstructured, prompt messages take Image/Audio by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3320
* Let Client take StdioServerParameters directly by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3321
* Gate external PRs on an assigned, linked issue by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3291
* docs: cover the remaining Tier 1 audit items by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3325
* Acknowledge notification POSTs with 202 on the 2026-07-28 HTTP entry by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3326
* Shorten stdio test comments by @Kludex in https://github.com/modelcontextprotocol/python-sdk/pull/3329
* Hand TypedDict tool results to pydantic natively by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3331
* Apply the request body limit to the SSE and OAuth endpoints by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3336
* Accept boolean sub-schemas in 2025-11-25 tool schema properties by @pja-ant in https://github.com/modelcontextprotocol/python-sdk/pull/3354
* Log MCPServer handler exceptions by kind and keep crash details off the wire by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3314
* Give recursive tool return types an object-rooted output schema by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3376
* docs: refresh translations for recent English changes by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3379
* Build releases with the pinned hatchling and a publish action that accepts Metadata 2.5 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3380
New Contributors
* @ShuQingDollarVoyager made their first contribution in https://github.com/modelcontextprotocol/python-sdk/pull/3245
Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/v2.0.0...v2.1.0
v1.29.12026-08-24
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
v2.0.02026-07-28
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.
``bash
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 (mcptypes.v), mcp.types is a permanent alias for mcptypes, 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.clientid, RFC7523OAuthClientProvider, and OAuthClientProvider(timeout=) are removed; the client-credentials providers take scope=; messagehandler receives notifications and exceptions only; FileResource(isbinary=) 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: https://github.com/modelcontextprotocol/python-sdk/compare/v2.0.0rc1...v2.0.0
v1.29.02026-07-28
What's Changed
[v1.x] Route Context.reportprogress() 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
v2.0.0rc1预发布2026-07-27
First v2 release candidate. Pre-releases are opt-in only; pip install mcp still resolves to the stable 1.x line.
``bash
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.clientid is removed - read meta via ctx.requestcontext.meta, or the authenticated client via getaccesstoken().clientid (#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 maxrequestbody_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 https://github.com/modelcontextprotocol/python-sdk/pull/3095
* docs: document Windows stdio subprocess stdin handling by @AndreKalberer in https://github.com/modelcontextprotocol/python-sdk/pull/3079
* docs: make API reference rendering independent of page order by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3107
* Pin pymdown-extensions back to 11.0 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3106
* docs: load media examples from disk instead of inline base64 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3108
Align with spec #3002: optional clientInfo, serverInfo in result meta by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3143
* Serve the 2026-07-28 protocol over stdio: decide the era from the opening request by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3152
* Isolate the stdio server's stdin and stdout from handler subprocesses by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3117
* Make CacheConfig() the Client cache default and None the off switch by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3164
Remove Context.clientid by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3167
* Rename scopes= to scope= on the client-credentials OAuth providers by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3166
* Correct stable v2 target date to 2026-07-28 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3105
* Remove the deprecated RFC7523OAuthClientProvider by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3169
Stop advertising MCP env vars for MCPServer settings; drop pydantic-settings by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3170
* Remove the unused timeout parameter from OAuthClientProvider by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3165
Narrow messagehandler's parameter to notifications and exceptions by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3168
Replace FileResource.isbinary with an encoding field by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3171
* Cache compiled output-schema validators on ClientSession by @jlowin in https://github.com/modelcontextprotocol/python-sdk/pull/3134
* Lengthen the demo signing keys in the identity-assertion examples by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3180
* Repin conformance harness to the published 0.2.0-alpha.10 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3184
* Point pre-release install pins at 2.0.0rc1 by @maxisbey in https://github.com/modelcontextprotocol/python-sdk/pull/3186
New Contributors
* @AndreKalberer made their first contribution in https://github.com/modelcontextprotocol/python-sdk/pull/3079
Full Changelog: https://github.com/modelcontextprotocol/python-sdk/compare/v2.0.0b2...v2.0.0rc1