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

MCP Python SDK v2.3.0：弃用空_meta/params

v2.3.0

原文
发到 X
推荐理由

v2.3.0 改变了 _meta/params 的序列化行为及工具注册的校验时机，使用 MCP Agent 或 Server 的开发者需检查代码是否依赖旧的空值语义或静默丢弃行为，建议尽快评估兼容性。

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

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

现在要求 httpx2>=2.10.0（#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.
  • 此前要求是 >=2.5.0。新的 max_sse_event_size 选项需要此版本。
  • 除非你将 httpx2 锁定在 2.10 以下，否则无需任何操作。

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

带有无效 x-mcp-header 注解的工具在注册时失败（#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.
  • @mcp.tool()、add_tool 和 Tool.from_function 会抛出 InvalidSignature 异常，并指明工具名称及问题所在。
  • 在此之前，服务器会正常启动，而 2026-07-28 客户端会静默地从其列表中移除该工具。
  • 被拒绝的情况包括：除普通 str、int 或 bool 参数之外的其他类型（因此也包括 str | None、float、列表和枚举）、非有效 token 的头部名称，以及仅大小写不同的两个名称。
  • 对于可选的头部参数，直接提供 schema：Annotated[str | None, WithJsonSchema({"type": "string", "x-mcp-header": "Region"})] = None。

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

空的 _meta 和 params 不再发送（#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.
  • 在 2025-11-25 及更早的连接中，2.x 会在每个请求中发送 "_meta": {}。某些服务器会拒绝该字段。现在像 v1 一样将其省略。
  • 不带游标的 ping 和 list 请求将不包含 params 成员。
  • 在接收端，ctx.meta 为 None 而非 {}；对于没有 params 的请求，中间件会将 ctx.params 视为 None。
  • 2026-07-28 连接保持不变。

initialize leaves out experimental when none is configured (#3614)

当未配置 experimental 时，initialize 会省略该字段（#3614）

  • It used to send "experimental": {}. server/discover already left it out.
  • Client code reading capabilities.experimental on a legacy connection should handle None.
  • 此前它会发送 "experimental": {}。server/discover 已经省略了该字段。
  • 在旧式连接上读取 capabilities.experimental 的客户端代码应处理 None 情况。

Mcp-Param-* validation looks the tool up by name (#3630)

Mcp-Param-* 验证按名称查找工具（#3630）

  • MCPServer no longer runs tools/list for every tools/call, so middleware no longer sees that extra request.
  • The registered schema is what gets checked. Middleware that filters or rewrites tools/list no longer affects it.
  • MCPServer 不再为每次 tools/call 运行 tools/list，因此中间件不再看到该额外请求。
  • 检查的是已注册的 schema。过滤或重写 tools/list 的中间件不再影响它。

An interactive OAuth login no longer counts against request timeouts (#3635)

交互式 OAuth 登录不再计入请求超时时间（#3635）

  • The timeout pauses while OAuthClientProvider waits on redirect_handler and callback_handler.
  • This fixes Client(mode="auto") settling on 2025-11-25 when the login took longer than 10 seconds.
  • A request timeout no longer ends a login nobody finishes. Put a limit inside callback_handler if you need one.
  • 当 OAuthClientProvider 等待 redirect_handler 和 callback_handler 时，超时计时器会暂停。
  • 此修复解决了当登录耗时超过 10 秒时，Client(mode="auto") 停留在 2025-11-25 的问题。
  • 请求超时不再导致无人完成的登录会话结束。如果需要，请在 callback_handler 内部设置限制。

New

新增

  • 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).
  • streamable_http_client 和 StreamableHttpParameters 中新增 max_sse_event_size= 参数。每个 SSE 事件的默认大小仍为 1 MiB；若需处理更大的工具结果，请调高该值或传入 None（#3600）。
  • MCPServer(subscriptions=False) 停止提供 subscriptions/listen 服务，并将 listChanged 和 subscribe 标记为 false（#3626）。
  • Server(get_tool_input_schema=...) 允许低级服务器在不运行其 tools/list 处理程序的情况下，为头验证提供工具的 schema（#3630）。
  • Client.call_tool 在收到 HeaderMismatch (-32020) 拒绝后，会重新列出工具并重试一次（#3627）。

Fixes

修复

  • ctx: Context[AppState] works on prompts and resource templates, not only on tools (#3624).
  • An explicit "structuredContent": null is checked against the output schema instead of being treated as missing (#3621).
  • A progress_callback that raises no longer fails the call on an in-process Client(server) (#3623).
  • Client OpenTelemetry spans record JSON-RPC error responses. With 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).
  • ctx: Context[AppState] 现在不仅适用于工具，还适用于 prompts 和资源模板（#3624）。
  • 显式的 "structuredContent": null 会与输出 schema 进行校验，而不再被视为缺失（#3621）。
  • 对于进程内 Client(server)，引发异常的 progress_callback 不再导致调用失败（#3623）。
  • Client OpenTelemetry spans 记录 JSON-RPC 错误响应。使用 mode="auto" 连接至没有 server/discover 的服务器时，探测操作将显示一个 ERROR span（#3629）。
  • stdio_client 在 Windows 上从事件循环解析可执行文件（#3510）。

Docs

文档

  • New pages: Cancellation and Header parameters, plus a middleware tutorial.
  • All twelve translations are refreshed (#3636).
  • 新增页面：取消和头参数，以及中间件教程。
  • 所有十二种翻译均已刷新（#3636）。

What's Changed

变更内容

  • Detect event-loop blocking in tests by @Kludex in #3510
  • Bump httpcore2 from 2.5.0 to 2.10.0 by @dependabot[bot] in #3482
  • Ask cubic for a review when the intake gate lets a PR back in by @maxisbey in #3489
  • docs: remove v2 notice from top of README by @claude[bot] in #3604
  • Bump anyio from 4.10.0 to 4.14.2 by @dependabot[bot] in #3547
  • Make the deeply nested body test independent of stack size by @maxisbey in #3610
  • Fall back to an NTFS junction when the symlink escape test can't create a symlink by @maxisbey in #3609
  • Group Dependabot security updates for uv dependencies by @Kludex in #3611
  • Expose an SSE event size limit in Streamable HTTP clients by @Kludex in #3600
  • Bump the github-actions group with 5 updates by @dependabot[bot] in #3612
  • docs: add a middleware tutorial that refuses tool calls by @maxisbey in #3613
  • Omit an unset experimental capability from the initialize result by @maxisbey in #3614
  • Document when a caller-supplied request id can be minted again by @maxisbey in #3619
  • Document the timeout a hand-built httpx2 client needs by @maxisbey in #3618
  • Reject a tool with an invalid x-mcp-header annotation at registration by @maxisbey in #3620
  • Validate an explicit null structuredContent against the output schema by @maxisbey in #3621
  • Contain a raising progress callback on the in-process dispatcher by @maxisbey in #3623
  • Keep the live Context when a prompt or template annotates Context[T] by @maxisbey in #3624
  • Describe the ID-JAG confidential-client rule as SDK policy, not a SEP-990 requirement by @maxisbey in #3622
  • Let MCPServer opt out of serving subscriptions/listen by @maxisbey in #3626
  • Document how a handler deals with cancellation by @maxisbey in #3625
  • Omit an empty _meta and empty params from outbound requests by @maxisbey in #3628
  • Record JSON-RPC error responses on the client OpenTelemetry span by @maxisbey in #3629
  • Retry a tool call once after a HeaderMismatch rejection by @maxisbey in #3627
  • Look the tool schema up by name for Mcp-Param-* validation instead of running tools/list by @maxisbey in #3630
  • Bump urllib3 from 2.7.0 to 2.8.0 by @dependabot[bot] in #3607
  • Let a newer Deploy Docs run cancel the one in progress by @maxisbey in #3633
  • Link What's new to the Header parameters page by @maxisbey in #3632
  • Keep inline-snapshot disabled when pytest runs in a terminal by @maxisbey in #3634
  • Stop counting an interactive OAuth login against request timeouts by @maxisbey in #3635
  • docs: refresh translations for recent English changes by @maxisbey in #3636
  • 由 @Kludex 在 #3510 中实现：在测试中检测事件循环阻塞
  • 由 @dependabot[bot] 在 #3482 中实现：将 httpcore2 从 2.5.0 升级至 2.10.0
  • 由 @maxisbey 在 #3489 中实现：当 intake gate 让 PR 返回时，请求 cubic 进行审查
  • 由 @claude[bot] 在 #3604 中实现：docs: 从 README 顶部移除 v2 通知
  • 由 @dependabot[bot] 在 #3547 中实现：将 anyio 从 4.10.0 升级至 4.14.2
  • 由 @maxisbey 在 #3610 中实现：使深层嵌套 body 测试独立于栈大小
  • 由 @maxisbey 在 #3609 中实现：当符号链接逃逸测试无法创建符号链接时，回退到 NTFS 联合点
  • 由 @Kludex 在 #3611 中为 uv 依赖项分组 Dependabot 安全更新
  • 由 @Kludex 在 #3600 中在 Streamable HTTP 客户端中暴露 SSE 事件大小限制
  • 由 @dependabot[bot] 在 #3612 中将 github-actions 组升级，包含 5 个更新
  • 文档：由 @maxisbey 在 #3613 中添加一个拒绝工具调用的中间件教程
  • 由 @maxisbey 在 #3614 中从初始化结果中省略未设置的实验性功能
  • 由 @maxisbey 在 #3619 中记录调用方提供的请求 ID 何时可以重新生成
  • 由 @maxisbey 在 #3618 中记录手动构建的 httpx2 客户端所需的超时时间
  • 由 @maxisbey 在 #3620 中在注册时拒绝带有无效 x-mcp-header 注解的工具
  • 由 @maxisbey 在 #3621 中根据输出模式验证显式 null structuredContent
  • 由 @maxisbey 在 #3633 中在处理内调度程序上包含引发异常的进度回调
  • 由 @maxisbey 在 #3624 中当提示或模板注解 Context[T] 时保持活动 Context
  • 由 @maxisbey 在 #3622 中将 ID-JAG 机密客户端规则描述为 SDK 策略，而非 SEP-990 要求
  • 由 @maxisbey 在 #3626 中允许 MCPServer 选择不提供订阅/监听服务
  • 由 @maxisbey 在 #3625 中记录处理程序如何处理取消操作
  • 由 @maxisbey 在 #3628 中从出站请求中省略空的 _meta 和空的 params
  • 由 @maxisbey 在 #3629 中在客户端 OpenTelemetry span 上记录 JSON-RPC 错误响应
  • 由 @maxisbey 在 #3627 中在 HeaderMismatch 拒绝后重试一次工具调用
  • 由 @maxisbey 在 #3630 中按名称查找工具模式以进行 Mcp-Param-* 验证，而不是运行 tools/list
  • 由 @dependabot[bot] 在 #3607 中将 urllib3 从 2.7.0 升级到 2.8.0
  • 由 @maxisbey 在 #3633 中允许较新的 Deploy Docs 运行取消正在进行的运行
  • 由 @maxisbey 在 #3632 中将“新增内容”链接到头部参数页面
  • 由 @maxisbey 在 #3634 中当 pytest 在终端中运行时保持 inline-snapshot 禁用状态
  • 由 @maxisbey 在 #3635 中停止将交互式 OAuth 登录计入请求超时
  • 文档：由 @maxisbey 在 #3636 中刷新近期英文更改的翻译

Full Changelog: v2.2.0...v2.3.0

完整更新日志：v2.2.0...v2.3.0

更进一步：量化金融体系

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

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

相似阅读

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