MCP Python SDK 弃用功能全指南:2026-07-28 规格迁移路线图与 MCPDeprecationWarning 实战

原创2026-09-21 14:42:151,399 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

MCP Python SDK 弃用功能全指南:2026-07-28 规格迁移路线图与 MCPDeprecationWarning 实战

2026-07-28 版 MCP 规格一次性让根目录(roots)、服务器发起式取样(sampling)、协议日志(logging)、ping 与客户端到服务器进度五类能力退场或移除,而本仓库的 Python SDK 仍完整实现它们,并在每次调用时发出可见的 MCPDeprecationWarning。本文以官方文档 i18n/zh-hant/pages/deprecated.md 为主线,结合 src/mcp 下的源码实现,讲清每一项弃用的原因、替代方案、mode="legacy" 的兼容用法,以及如何用一行 pytest 配置把弃用调用变成回归测试。

哪些被弃用:一张表看清五类能力

弃用项目 原因 替代做法
根目录(roots):ctx.session.list_roots()、client.send_roots_list_changed()、传给 Client(...) 的 list_roots_callback= SEP-2577)。
服务器发起的取样(sampling):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() 回报进度(见 进度)。

从这张表可以看出三件事:

  • 根目录、取样和日志是一起的:同一份提案 SEP-2577 一次性弃用了这三项能力。
  • 取样和根目录共享一个更深层的问题:它们都是服务器向客户端发送请求的地方。2026-07-28 用 多轮往返请求 取代的正是这整个方向。消失的是那些独立的 RPC 方法(sampling/createMessage、roots/list,以及推送式的 elicitation/create);而 CreateMessageRequest、ListRootsRequest、ElicitRequest 这些载荷类型保留了下来,嵌入 InputRequiredResult.input_requests 里,在客户端会触发同样的回调。
  • ping 是特例:协议不是弃用而是移除它。SDK 方法仍然会发出警告(消息写的是 removed 而不是 deprecated),在现代连接上调用它,得到的回应是 "Method not found"。

在源码里可以逐一印证这些弃用注解:例如 src/mcp/server/context.py 中 ctx.log() 标注为 @deprecated("The logging capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning);src/mcp/server/session.py 的 list_roots() 与 create_message() 系列同样标注了 SEP-2577 弃用;而 src/mcp/client/client.py 的 client.send_ping() 则标注 "ping is removed as of 2026-07-28; the method only works under mode='legacy'.",消息用词刻意与"弃用"区分。

弃用只是劝告性质:今天什么都不会坏

上面每个方法,在任何协商到 2025-11-25 或更早版本的会话(session)上都能继续运作。在客户端固定 mode="legacy",就能得到和 2026 之前完全一样的行为——线路上没有任何变更,能力协商也维持不变。

改变的只是:每个方法第一次执行时,你会看到一条明显的警告:

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

为什么是 UserWarning 而不是 DeprecationWarning

MCPDeprecationWarning 继承自 UserWarning,不是 DeprecationWarning。这是刻意为之。其定义位于 src/mcp/shared/exceptions.py:

class MCPDeprecationWarning(UserWarning):
    """A custom deprecation warning for the MCP SDK.

    Unlike the built-in `DeprecationWarning`, this inherits from `UserWarning` so
    it is shown by default, helping users discover deprecated features without
    enabling warnings explicitly.
    """

原因在于 Python 的默认过滤器只在直接以 __main__ 执行的代码里显示 DeprecationWarning——这正是"函数库弃用了某样东西,却两年都没人注意到"的经典陷阱。继承 UserWarning 后,这个警告到处都会出现,不需要 -W 旗标,从而让升级者第一时间注意到自己触碰了废弃 API。

"劝告性质"止步于线路:反向通道的硬限制

需要注意的是,MCPDeprecationWarning 的"劝告性"只到线路为止。取样和根目录是服务器对客户端的请求,而 2026-07-28 的会话没有通道可以承载它。在现代连接上于工具内调用 ctx.session.create_message(),警告照样发出,接着发送会失败并抛出错误:

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

两个信号按顺序出现:

  1. MCPDeprecationWarning 在调用方法的那一刻发出,任何连接都一样;
  2. 错误则是 SDK 接着尝试发送时返回的。

这条错误的实现源头是 src/mcp/shared/exceptions.py 中的 NoBackChannelError,其消息格式为 Cannot send {method!r}: this transport context has no back-channel for server-initiated requests.,序列化为 INVALID_REQUEST 错误响应;list_roots() 的 docstring 也明确声明:连接没有反向通道时抛出 NoBackChannelError。

这两个信号只有在客户端注册了对应回调的 mode="legacy" 连接上,才能从头到尾正常工作。

旧版会话上的 ping:特例中的兼容用法

ping 是一个空请求,任何一方都可以发送,用来确认对方还有回应。2026-07-28 规格移除了它(SEP-2575):现代客户端发出的每个请求本身就已证明服务器还在,而现代服务器也没有通道可以发出 ping。不过两个 SDK 方法在握手时代(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。
  • ctx.session.send_ping() 不携带警告。在现代连接上,它和其他任何服务器发起的请求一样,引发"没有反向通道"(no back-channel)的错误。
  • 两边都不需要注册任何东西来回应 ping。

在 src/mcp/client/client.py 可以看到 mode 的完整类型定义:ConnectMode = Literal<a href="https://link.gitcode.com/i/c3bcfbe82acd25d513d4ea6004a1b3cf" target="_blank">"legacy", "auto"] | str。"legacy" 走的是 InMemoryTransport + JSONRPCDispatcher 的经典握手路径([src/mcp/client/client.py),而现代模式走 DirectDispatcher 的每请求直连路径,因此只有 "legacy" 能完整保留服务器发起请求的反向通道。

根目录变更通知:notifications/roots/list_changed 的前世今生

声明了根目录能力的 2025 世代客户端,可以发送 notifications/roots/list_changed 告诉服务器它的工作区文件夹变了;服务器的回应是再次请求 roots/list。2026-07-28 规格把这个通知连同其余推送式根目录流程一起移除。

在客户端,传入 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= 用来注册处理函数(同样已弃用,构造时就会发出警告)。这个通知不携带任何载荷,所以处理函数要调用 ctx.session.list_roots() 取得新清单。

源码侧,client.send_roots_list_changed() 在 src/mcp/client/client.py 标注为 SEP-2577 弃用,而服务器端的 ctx.session.list_roots() 在 src/mcp/server/session.py 同样带弃用注解并声明会抛出 NoBackChannelError。

让警告静音:什么时候可以做,以及怎么把警告变成测试失败

新代码里,不要做这件事。但如果你维护的服务器确实在服务 2026 之前的客户端,它完全有权利保持日志干净。在第一个已弃用调用执行之前,先过滤掉这个类别:

import warnings

from mcp import MCPDeprecationWarning

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

这就是整个 API——没有逐方法的开关,你也不会想要:只用一个类别的意义在于,一行就能关掉它,一行就能把它叫回来。

把过滤器反过来:一行 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 配置,已弃用的调用就再也无法在不导致测试失败的情况下溜回代码库。顺带一提,mcp 包从 src/mcp/init.py 顶层导出 MCPDeprecationWarning,所以 from mcp import MCPDeprecationWarning 即可直接使用。

已弃用的 SDK 辅助函数:不是规格变更,同样 3.0 移除

以下几项不是规格变更,只是有了更好替代做法的 SDK 用法。它们用同样的 MCPDeprecationWarning 发出警告,旧写法会在 3.0 移除。

弃用项目 替代做法
FuncMetadata.call_fn_with_arg_validation() 先 FuncMetadata.validate_arguments(),再 FuncMetadata.call_fn()。只有直接操作 FuncMetadata 的代码(例如自定义的 Tool 子类)才会调用过它。
没有设置 validate_token_resource= 的 AuthSettings(resource_server_url=...) 把它设好:True 会让服务器拒绝验证器没有回报为核发给 resource_server_url 的 bearer 令牌;False 表示你的验证器会自己检查令牌的 audience(见 授权)。不设置时行为等同 False;3.0 起,只要设置了 resource_server_url,默认就是 True。
没有传入 issuer= 的 ClientCredentialsOAuthProvider(...) 或 PrivateKeyJWTOAuthProvider(...) 传入 issuer=,指明核发这组凭据的授权服务器(见 编写 OAuth 客户端)。少了它,就变成由 MCP 服务器决定哪个授权服务器收到这组凭据;3.0 会把这个关键字参数改为必填。

重点回顾

  • 2026-07-28 规格弃用了根目录、服务器发起的取样和协议日志(全部来自 SEP-2577),把进度限制为只能从服务器到客户端,并移除了 ping。
  • 替代做法那一栏指引你接下来往哪走:取样和根目录看 多轮往返请求,日志看 日志,进度看 进度。ping 什么都不需要。
  • 弃用只是劝告性质:线路没有变更,一切在 2026 之前的会话上都能继续运作,而且你会看到明显的 MCPDeprecationWarning(它是 UserWarning,所以默认就会显示)。
  • 取样和根目录还额外需要一条反向通道,而 2026-07-28 的会话没有。在现代连接上,它们会先警告、再抛出异常。
  • warnings.filterwarnings("ignore", category=MCPDeprecationWarning) 会让整个类别静音;pytest 里的 "error::mcp.MCPDeprecationWarning" 则把它变成测试失败。
  • SDK 层级的弃用遵循同样的规则:现在发出警告,3.0 移除旧写法。
  • 新代码不应该建立在这些东西之上——这套文档的每一页教的都是当前 API。
登录后查看全文
python-sdk