MCP Python SDK 弃用功能全指南:2026-07-28 规格迁移路线图与 MCPDeprecationWarning 实战
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.
两个信号按顺序出现:
MCPDeprecationWarning在调用方法的那一刻发出,任何连接都一样;- 错误则是 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。