跳到主内容
@wquguru
精选85MCP Python SDK（GitHub Releases）AI 编程与模型

MCP Python SDK v2.2.0：默认行为变更，闲置会话过期与重定向限制

v2.2.0

原文
发到 X
推荐理由

MCP Python SDK 是 AI 编程与模型开发的核心依赖，本次默认行为变更（重定向限制、闲置会话过期）可能影响现有服务器和客户端，建议开发者升级前仔细阅读变更说明，并调整相关配置。

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

pip install -U mcp。文档：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:

此版本中一些默认值发生了变化。如果你在 2.x 上运行服务器或客户端，请先浏览以下内容：

Behaviour changes

行为变更

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

HTTP 客户端重定向仅在端点来源内被跟随 (#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.
  • Client("https://...")、streamable_http_client 和 sse_client 仅在重定向保持相同协议、主机和端口（或在同一主机上从 http 升级到 https）时才跟随重定向。
  • 任何其他位置的重定向都不会被跟随：调用会以 MCPError 失败，并且会话保持可用（SSE 连接会以 httpx2.HTTPStatusError 失败）。如果那个其他 URL 是你想要的服务器，请将其用作端点 URL。
  • 你传入的 httpx2.AsyncClient 上的 follow_redirects 设置不再用于 MCP 请求，因此你不再需要它来处理尾斜杠重定向。
  • OAuth 提供程序对其自身请求也应用相同规则。

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

空闲的 Streamable HTTP 会话现在会过期（旧版 <=2025-11-25 规范）(#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()).
  • 一个状态会话如果 30 分钟内没有任何活动，将被关闭。客户端的下一个请求将收到 404，并且必须重新初始化。
  • 保持 GET 流打开的客户端（SDK 的 Client 会这样做）不受影响。无状态服务器或 2026-07-28 连接也不受影响。
  • 服务器同时最多持有 10,000 个会话；超过此数量，新会话将收到 503。
  • 要关闭任一功能：mcp.run(transport="streamable-http", session_idle_timeout=None, max_sessions=None)（也适用于 streamable_http_app() 和 run_streamable_http_async()）。

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

OAuth 客户端现在也在旧路径上检查授权服务器的 issuer (#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.
  • 对于没有受保护资源元数据的服务器，如果授权服务器元数据的 issuer 不是服务器自身的来源，现在会被拒绝并抛出 OAuthFlowError：授权服务器元数据 issuer 不匹配。受保护资源元数据路径自 2.0 起已执行此操作。
  • 不是 insufficient_scope 挑战的 403 错误会返回给调用者，而不是重试。
  • 如果由于 5xx/429 错误而无法获取受保护资源元数据，流程现在会停止，而不是回退到旧端点。

Two new MCPDeprecationWarnings (#3435, #3447)

两个新的 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.
  • ClientCredentialsOAuthProvider / PrivateKeyJWTOAuthProvider 未设置 issuer=。请传递你的授权服务器的 issuer URL；3.0 将要求提供。
  • AuthSettings 设置了 resource_server_url 但未设置 validate_token_resource。请将其设置为 True 或 False；3.0 默认将其设为 True。
  • 两者在 2.x 中仍像以前一样工作；如果你的测试将警告视为错误，这一点就很重要。

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).
  • AuthSettings.validate_token_resource：仅接受您的 TokenVerifier 报告为为此服务器签发的令牌（#3447）。
  • 在 ClientCredentialsOAuthProvider 和 PrivateKeyJWTOAuthProvider 上添加 issuer= 参数（#3398）。
  • 在 Streamable HTTP 服务器入口点上添加 session_idle_timeout= 和 max_sessions= 参数（#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).
  • 客户端 DELETE 会立即释放其会话，被拒绝的打开请求不再留下会话（#2455, #3228, #3300）。
  • 工具 outputSchema 中的 $refs 仅在该 schema 内解析；无法解析的引用会以 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.

任务扩展（SEP-2663）、DPoP（SEP-1932）和 jwt-bearer 授权尚未实现；https://github.com/modelcontextprotocol/python-sdk/blob/main/ROADMAP.md 跟踪这些项目。

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
  • 也门控草稿 PR，并重写自动关闭评论，由 @maxisbey 在 #3378 中完成
  • 仅解析工具输出 schema 文档中的引用，由 @maxisbey 在 #3394 中完成
  • 默认过期空闲的 Streamable HTTP 会话并限制并发会话，由 @maxisbey 在 #3395 中完成
  • 在每个发现路径上验证授权服务器元数据颁发者，由 @maxisbey 在 #3398 中完成
  • 弃用不带颁发者构造预置 OAuth 客户端，由 @maxisbey 在 #3435 中完成
  • 在一致性测试夹具中练习 SEP-2575 无状态探测和 SEP-2243 资源/提示头，由 @maxisbey 在 #3442 中完成
  • 将 github-actions 组提升 6 个更新，由 @dependabot[bot] 在 #3424 中完成
  • 将文档预览工作流脚本从 YAML 移到 .github/scripts，由 @maxisbey 在 #3446 中完成
  • 跳过 fork PR 的自动文档预览，并移除 setup-uv 重试步骤，由 @maxisbey 在 #3445 中完成
  • 仅跟随 MCP 端点源内的重定向，由 @maxisbey 在 #3397 中完成
  • 将 pymdown-extensions 从 11.0 提升到 11.0.1，由 @dependabot[bot] 在 #3285 中完成
  • 提升八个开发与测试依赖的锁定版本，由 @maxisbey 在 #3449 中完成
  • 当端点 URL 携带用户信息时，继续跟随相对重定向，由 @maxisbey 在 #3450 中完成
  • 添加 AuthSettings.validate_token_resource 以检查承载令牌的资源，由 @maxisbey 在 #3447 中完成
  • 文档：停止将内存客户端呈现为连接方式，由 @maxisbey 在 #3443 中完成
  • 文档：也要求对评论进行AI披露，由@maxisbey在#3459中提出
  • 文档：刷新翻译，并并行翻译页面，由@maxisbey在#3458中提出
  • 用类型别名和TypeAdapter验证替换RootModel包装器，由@Kludex在#3470中提出

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

完整变更日志：v2.1.1...v2.2.0

更进一步：量化金融体系

看懂新闻只是起点——沿量化金融路径，把它变成能交付的工程能力

进入量化体系 →
话题#破坏性#MCP#Python SDK#Streamable HTTP#OAuth

相似阅读

关联信息，但可能不是同一事件