MCP 2.0 SDK 迁移导致大量 AI 工具集体失效

如果你在跑任何用 MCP 的 AI 工具，最近几周可能不太好过。GitHub issues 里反复出现同一个模式：有人做了一次常规更新，结果 MCP 服务器"突然就不工作了"。没有报错，或者只有一个莫名其妙的错误。网关报告健康状态，服务器说已启用，但工具就是不出来。

这个问题在同一时间段内波及了很多不同的工具。AutoGen 的 MCP 扩展、LlamaIndex 的 MCP 工具、Copilot CLI、Claude Desktop 配置、还有几个我就不点名的 Agent 框架……全都以大致相同的方式挂掉了。这不是随机的坏运气。

共同的线索是：mcp Python SDK 在 7 月底附近跃升到了 2.0.0，而 2.0.0 带来了破坏性变更。一堆包装库把 mcp 锁定在 >=1.x 且没有上限，所以下一次更新就拉来了 2.0.0，所有基于旧 API 构建的东西全部倒下。

实际发生了什么

几个具体的、机械式的破坏点：

streamable_http_client() 以前返回的是一个 3 元组。现在变成 2 元组了。用旧代码解包三个值会在启动时抛出 ValueError。

名称变了。streamablehttp_client 变成了 streamable_http_client。只检查旧名称的代码会悄无声息地失去 HTTP 传输。

类型从 camelCase 变成了 snake_case。.inputSchema 现在是 input_schema，.isError 现在是 is_error。

客户端现在只接受 JSON Schema draft 2020-12，不再支持 draft-07。声明了旧 $schema 的服务器会被直接拒绝。

协议握手变了（现代 server/discover 对上旧式 initialize），这才是绊倒 Copilot CLI 的原因。

这些都不是恶意的。major 版本就是会 break 东西。真正令人恼火的是，生态里很多地方没有给依赖加上限，所以破坏一直静默着，直到你做了更新。

如何确认是这个问题

检查你正在用的版本：

pip show mcp
# 或
uv pip show mcp

如果是 2.0.0 而你的工具是基于 1.x 构建的，那几乎可以确定就是它。不需要复现，不需要翻配置考古。

大多数时候，锁回到你工具所基于的版本：

pip install "mcp<2"
# 或者恢复你工具声明的确切锁定，例如
pip install "mcp==1.28.1"

几个值得知道的具体情况：

AutoGen (autogen-ext[mcp])：锁定 mcp<2。上游限定在 >=1.11,<2。

LlamaIndex (llama-index-tools-mcp)：锁定到 0.4.x，或者给 client.py 打补丁，将解包从 3 元组改成 2 元组（read, write）。Session 会立即恢复正常。

Copilot CLI：锁定到 1.0.81-0。81-1 构建是那个回归版本。

Hermes：恢复锁定的 mcp 和 starlette，重启网关，然后运行 mcp test 确认工具重新连接。

有一个情况没有干净的锁定方案：如果你 MCP 服务器的 schema 方言被拒绝了（Claude Desktop 里那个 draft-07 错误），客户端现在只认 2020-12。已验证的临时解决方案是一个薄薄的 stdio 代理，把 outputSchema $schema 重写为 2020-12。丑，但能用。

我可以继续讲具体细节，但说实话结论很无聊：给你的依赖加锁定。如果一个工具的更新器拉了一个没有上限的 major 版本过来，而声明的是 minor 锁定，那是更新器的 bug，但你可以通过不让链式更新乱跑来保护自己。

当你更新 AI 工具时，更新后瞄一眼 mcp 的版本。如果 MCP 服务器安静了且没有明显错误，在开始拆配置之前先检查这个包。

我可能说错了，但我现在已经在一周内看到了五个不同厂商的完全相同的失败，同一根因，同一类的修复方法。如果你的 MCP 设置在更新后坏了，而没有别的解释，你的 mcp 包版本值得一看。在你删掉配置之前先试试这个。