MCP Python SDK 弃用功能完全指南:2026-07-28 规范迁移与兼容策略
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)。
由总览表推出的三个结论
- 根目录、采样、日志三者同进退:它们同属一份提案 SEP-2577,一次被全部宣告弃用。
- 采样和根目录背后是同一个深层问题:二者都是"服务器向客户端发请求"的场景,而 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发送,协议方法名与载荷类型保持不变。 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: callvalidate_argumentsand thencall_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 实际行为不会脱节。