MCP Python SDK 弃用功能完全指南:2026-07-28 规范迁移与兼容策略

原创2026-09-20 12:07:221,756 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

MCP Python SDK 弃用功能完全指南:2026-07-28 规范迁移与兼容策略

导读

Model Context Protocol(MCP)官方 Python SDK(python-sdk)在 2026-07-28 规范中正式将根目录(roots)、服务器主动采样(sampling)、协议日志(protocol logging)、客户端到服务器进度(progress)与 ping 五项能力列为弃用或直接移除。本文以 SDK 官方文档 docs/deprecated.md 为骨架,结合 src/mcp 源码与 tests/docs_src/test_deprecated.py 测试,逐项说明"什么被弃用、为什么、改用谁",并给出 legacy 模式兼容、警告抑制、pytest 回归拦截的完整实操方案,帮助你安全地把存量服务迁到 2026 协议代际。


一、弃用总览:五件事 + 三组 SDK 级弃用

2026-07-28 规范总共退出了五类协议能力,SDK 对每一项都继续保留实现,但每次调用都会发出 MCPDeprecationWarning 弃用警告。另有几项 SDK 层面的用法弃用(非规范变更)单独列在文末小节。

已弃用内容 弃用原因 替代方案
根目录(roots):ctx.session.list_roots()、client.send_roots_list_changed()、传给 Client(...) 的 list_roots_callback= SEP-2577 将该能力整体退出 把路径作为普通工具参数或资源 URI 传入;或将 ListRootsRequest 嵌入 InputRequiredResult(见多轮往返请求)
服务器主动采样:ctx.session.create_message()、传给 Client(...) 的 sampling_callback= SEP-2577 将该能力整体退出 返回 InputRequiredResult,让客户端重试调用(见多轮往返请求)
协议日志:ctx.log()、ctx.debug()、ctx.info()、ctx.warning()、ctx.error()、ctx.session.send_log_message()、client.set_logging_level() SEP-2577 将该能力整体退出,协议内无替代品 改用标准 import logging 输出到 stderr(见日志)
ping:client.send_ping() 不是"弃用",而是被直接移除——2026-07-28 协议中已不存在 ping 方法 无需任何替代;只有 mode="legacy" 连接上还能用
客户端到服务器进度:client.send_progress_notification() 2026-07-28 中进度只允许服务器→客户端单向传递 没有要发送的内容;进度由你的服务器通过 ctx.report_progress() 上报(见进度)

从源码看,客户端侧这些弃用方法都集中在 src/mcp/client/client.py 中,并统一使用 typing_extensions.deprecated 装饰器标注,例如 send_ping(client.py#L521-L527)、send_progress_notification(client.py#L529-L533)、set_logging_level(client.py#L548-L549)与 send_roots_list_changed(client.py#L946-L949)。

由总览表推出的三个结论

  1. 根目录、采样、日志三者同进退:它们同属一份提案 SEP-2577,一次被全部宣告弃用。
  2. 采样和根目录背后是同一个深层问题:二者都是"服务器向客户端发请求"的场景,而 2026-07-28 规范用多轮往返请求整体取代了这个方向。被移除的是独立 RPC 方法(sampling/createMessage、roots/list 以及 push 风格的 elicitation/create);而 CreateMessageRequest / ListRootsRequest / ElicitRequest 这些载荷类型得以保留——它们被嵌入 InputRequiredResult.input_requests,在客户端侧仍会命中同一个回调。这一点在 src/mcp/shared/peer.py 中体现得很清楚:sample(peer.py#L88-L157)与 list_roots(peer.py#L221-L231)仍被 @deprecated 装饰,但方法体只是把参数组装后通过 send_raw_request 发送,协议方法名与载荷类型保持不变。
  3. ping 是例外:协议不是"弃用"它,而是删除它。SDK 方法依旧会发警告(警告文案说的是 removed 而不是 deprecated),且在当代连接上调用会得到 "Method not found"。

二、弃用是"建议性"的:legacy 模式下一切照旧

现阶段没有任何东西会立即损坏。 上面列出的所有方法,在任何协商到 2025-11-25 或更早版本的会话中都能继续工作。在客户端固定 mode="legacy",你就能得到与 2026 年之前完全一致的行为——线上数据格式没有任何变化,能力协商逻辑也保持不变。

唯一的变化是:每个被弃用方法首次运行时会出现一条醒目的警告:

MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).

这里有个刻意的设计细节值得注意:MCPDeprecationWarning 继承自 UserWarning,而不是 DeprecationWarning(见 src/mcp/shared/exceptions.py#L8)。原因是 Python 的默认警告过滤器只在以 __main__ 直接运行的代码里展示 DeprecationWarning——这正是库作者惯用的弃用方式,结果往往两年都没人注意到。而 MCPDeprecationWarning 不需要任何 -W 标志,在任何地方都会显示。tests/docs_src/test_deprecated.py#L110-L117 用 issubclass 断言锁定了这一行为:它是 UserWarning 的子类,且不是 DeprecationWarning 的子类。

"建议性"止步于网络层

重要警告:采样和根目录是"服务器→客户端"的请求,而 2026-07-28 会话中不存在承载这种请求的通道。在当代连接上于工具内部调用 ctx.session.create_message(),警告依然会触发,但随后发送会以错误告终:

Cannot send 'sampling/createMessage': this transport context has no back-channel
for server-initiated requests.

注意这两个信号的先后顺序:MCPDeprecationWarning 在调用方法的那一刻触发,任何连接上都一样;错误则是 SDK 随后尝试发送请求时才返回的。这两项能力端到端只能在 mode="legacy" 连接上工作,且要求客户端注册了对应的回调。

这条错误信息由 src/mcp/shared/exceptions.py#L55-L71 的 NoBackChannelError 产生:DispatchContext.send_raw_request 在发现请求作用域的通道报告 TransportContext.can_send_request 为 False 时抛出该异常,并序列化为 INVALID_REQUEST 错误响应。测试 test_create_message_warns_and_then_raises_on_a_modern_connection 用 pytest.warns + pytest.raises 精确验证了"先警告、后抛错"的顺序与错误文案。


三、在 legacy 会话中使用 ping

Ping 是一个空请求,任何一方都可以用它探测对方是否仍在响应。2026-07-28 规范通过 SEP-2575 将其删除,理由是:现代客户端发出的每一个请求本身就已证明服务器在线,而现代服务器又没有发送 ping 的通道。不过 SDK 的两个 ping 方法在握手代际(handshake-era)会话中依然可用。

客户端侧:

async def main() -> None:
    async with Client("http://localhost:8000/mcp", mode="legacy") as client:
        await client.send_ping()  # 发出警告;返回一个 EmptyResult

服务器侧,在任意处理器内部:

@mcp.tool()
async def check_client(ctx: Context) -> str:
    """A tool that still pings the client mid-call."""
    await ctx.session.send_ping()  # 无警告;客户端在线时返回 EmptyResult
    return "client answered"

行为要点:

  • client.send_ping() 每次调用都会触发 MCPDeprecationWarning。在默认(2026-07-28)连接上,服务器会以 MCPError: Method not found 作答。测试 test_send_ping_still_carries_the_deprecation_warning 验证了警告文案为 ping is removed as of 2026-07-28; the method only works under mode='legacy'.,并断言现代连接上确实抛出 Method not found。
  • ctx.session.send_ping() 不带警告。在当代连接上,它抛出与任何服务器主动请求相同的"无反向通道"错误(NoBackChannelError)。
  • 双方都不需要注册任何东西来响应 ping。

四、根目录变更通知(roots change notifications)

2025 代际的客户端如果声明了根目录能力,可以在工作区文件夹变化时向服务器发送 notifications/roots/list_changed,服务器随后会重新请求 roots/list。2026-07-28 规范连同整个 push 风格根目录流程一起删除了这个通知。

在客户端,正是传入 list_roots_callback=(参见客户端回调)才会声明 "roots": {"listChanged": true},而兑现这个承诺只需要一次调用:

async def open_folder(client: Client, uri: str, name: str) -> None:
    """The user opened another folder: expose it through the roots callback, then tell the server."""
    workspace.append(Root(uri=FileUrl(uri), name=name))
    await client.send_roots_list_changed()

在服务器侧,接收处理器注册在低层 Server 类上:

async def roots_changed(ctx: ServerRequestContext, params: NotificationParams | None) -> None:
    """The client's roots changed: ask for the new list."""
    roots = (await ctx.session.list_roots()).roots


server = Server("Bookshop", on_roots_list_changed=roots_changed)

细节说明:

  • workspace 是你的 list_roots_callback 返回的列表。client.send_roots_list_changed() 会发出警告,且要求客户端处于 mode="legacy":在当代连接上,该通知会被静默丢弃。发送后请保持会话打开,因为服务器后续的 roots/list 请求会经由这条会话到达。
  • MCPServer(高层封装)没有接入该通知的钩子;只有低层 Server 通过 on_roots_list_changed= 注册处理器(该参数同样已弃用,在构造对象时就会发出警告,见 src/mcp/server/lowlevel/server.py#L404-L409)。通知不携带载荷,因此处理器通过 ctx.session.list_roots() 获取新列表。

从源码层面看,list_roots 在服务器会话中同样被 @deprecated 装饰(src/mcp/server/session.py#L316-L317),协议路由仍注册在 notifications/roots/list_changed 上(src/mcp/server/lowlevel/server.py#L466),与文档描述完全吻合。


五、抑制警告:静音与反向利用

新代码中请不要抑制警告。 但如果你维护的服务器确实需要服务 2026 年之前的客户端,那么让日志保持安静是合理的。在第一个弃用调用执行之前过滤掉该类别即可:

import warnings

from mcp import MCPDeprecationWarning

warnings.filterwarnings("ignore", category=MCPDeprecationWarning)

这就是完整的 API——没有针对单个方法的开关,也不需要:统一类别的好处正是"一行代码静音、一行代码恢复"。MCPDeprecationWarning 从 mcp 包顶层导出(见 src/mcp/init.py#L71),无需深层导入。

反向利用:一行 pytest 配置换一个免费回归测试

把过滤器反过来,你就能得到免费的回归测试。在 pytest 配置的 filterwarnings 参数中加入 "error::mcp.MCPDeprecationWarning",弃用调用将从"警告"变成"抛异常"。例如,一个名叫 old_log、仍调用 ctx.info() 的工具会直接测试失败:调用以 is_error=True 返回,文本为 Error executing tool old_log,捕获到的服务器日志会点名肇事者:

mcp.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).

仅仅一行 pytest 配置,弃用调用就再也无法悄悄混回代码库而不破坏测试。这一行为由 test_error_filter_turns_the_deprecated_call_into_the_documented_tool_error 完整复现:在 @pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning") 下调用 old_log 工具,断言结果 is_error=True、文本为 Error executing tool old_log,且日志记录的异常链原因正是 The logging capability is deprecated as of 2026-07-28 (SEP-2577).。反向静音方案则由 test_filterwarnings_ignore_silences_the_whole_category 验证:filterwarnings("ignore", ...) 之后同一工具正常返回、无任何捕获警告。


六、SDK 级弃用:仅限 SDK 用法的替代方案

以下不是规范变更,而是 SDK 自身用法有了更好的替代。它们同样触发 MCPDeprecationWarning,且在 3.0 版本中旧形式将被删除。

已弃用 替代方案
FuncMetadata.call_fn_with_arg_validation() 先 FuncMetadata.validate_arguments(),再 FuncMetadata.call_fn()。只有直接驱动 FuncMetadata 的代码(例如自定义 Tool 子类)才会调用它。
AuthSettings(resource_server_url=...) 但未指定 validate_token_resource= 显式设置它:True 表示服务器拒绝你的验证器未报告为"为 resource_server_url 签发"的 bearer 令牌;False 表示由你的验证器自行检查令牌受众(见授权)。未设置时行为等同 False;3.0 中只要设置了 resource_server_url,True 将成为默认值。
调用 ClientCredentialsOAuthProvider(...) 或 PrivateKeyJWTOAuthProvider(...) 但未传 issuer= 传入 issuer= 指明签发这些凭证的授权服务器(见编写 OAuth 客户端)。不传时由 MCP 服务器自行决定把凭证交给哪台授权服务器;3.0 中该关键字参数将变为必填。

从源码可以印证这三处的实现细节:

  • FuncMetadata 的弃用路径在 src/mcp/server/mcpserver/utilities/func_metadata.py:validate_arguments(#L139)与 call_fn(#L149)是推荐路径,而 call_fn_with_arg_validation(#L171-L183)的 docstring 明确写着 "Deprecated: call validate_arguments and then call_fn",其实现本质是先验证再调用。
  • AuthSettings 的校验逻辑在 src/mcp/server/auth/settings.py:当 validate_token_resource 未设置但 resource_server_url 已设置时,模型校验器 _check_validate_token_resource(#L58-L64)会发出"将在 3.0 中默认 True"的弃用警告;若 validate_token_resource=True 却没有 resource_server_url,则直接抛出 ValueError。
  • OAuth 提供者侧,_checked_issuer(src/mcp/client/auth/extensions/client_credentials.py#L27-L39)在 issuer=None 时发出"省略 issuer 已弃用、3.0 中必填"的警告,并校验 issuer 必须是 http(s) 的 issuer URL;_require_metadata_for_configured_issuer(#L49-L64)保证配置了 issuer 后,令牌请求只会基于该 issuer 发现的授权服务器元数据构建。

七、总结

  • 2026-07-28 规范弃用了根目录、服务器主动采样与协议日志(三者均出自 SEP-2577),把进度限定为服务器→客户端单向,并移除了 ping。
  • 替代方向很清晰:采样与根目录走向多轮往返请求,日志改用标准 logging(见日志),进度用服务器侧 ctx.report_progress()(见进度);ping 则什么都不需要。
  • 弃用是建议性的:线上数据格式不变,一切在 2026 年之前的会话中照常工作,只是会出现一条默认可见的 MCPDeprecationWarning(继承自 UserWarning,因此默认开启)。
  • 采样与根目录还需要一条 2026-07-28 会话不具备的反向通道:在当代连接上,它们先警告、后抛异常(NoBackChannelError)。
  • warnings.filterwarnings("ignore", category=MCPDeprecationWarning) 可静音整个类别;pytest 配置里的 "error::mcp.MCPDeprecationWarning" 则把它变成测试失败。
  • SDK 级弃用遵循同样的规则:现在只警告,3.0 将删除旧形式。
  • 新代码不应建立在任何这些能力之上。

文档其余所有页面讲授的都是当前的 API,而本文对应的行为承诺均有自动化测试背书(tests/docs_src/test_deprecated.py),确保文档叙述与 SDK 实际行为不会脱节。

登录后查看全文
python-sdk