博客 / 开发工具

MCP 工具不显示怎么办：2026-07-28 新规范下的 5 步排查（2026 年 10 月）

2026-10-18cdnping 编辑部约 4 分钟读完

升级 Claude Code 或其他客户端之后，如果 MCP 工具突然不显示，先怀疑协议版本：2026-07-28 版 MCP 规范正在成为各客户端的默认协商版本，而旧版服务端或没完全实现新字段的服务端，可能被连上却拿不到工具。最快的验证办法是设置 MCP_PROTOCOL_NEGOTIATION=legacy 退回旧协商（更新日志写明该开关用于 claude.ai 连接器、云会话和 Remote Control 连接器的协商），工具回来了，问题多半出在版本上。本文以 2026 年 10 月为时间口径，下面的版本号以各项目公开的更新日志为准。

#这次到底改了什么？

MCP 官方博客在 2026 年 7 月 28 日发布了 2026-07-28 版规范，8 月 22 日又发布了新路线图（见 MCP 官方博客）。与排查相关的变化有这几项（据该博客文章）：

• 核心改为无状态：initialize/initialized 握手和 Mcp-Session-Id 头被取消，每个请求自带协议版本、客户端信息和能力。
• 新增可选的 server/discover，想提前了解服务端能力的客户端可以调用，但不是必须。
• 服务端需要用户输入时，返回 resultType: "input_required"，客户端带着答案重试。
• tools/list、prompts/list、resources/list、resources/read 的响应带有 ttlMs 和 cacheScope，供客户端决定缓存策略。

握手没了。2.1.302 的修复说明，服务端若协商了新版本却缺少这些字段，会出现工具为空的情况。

#各客户端现在是什么状态？

注意 Codex 这一条是 OAuth 方面的能力，不是协议版本切换，别把两件事混在一起排查。

#工具不显示时怎么一步步排查？

#第 1 步：客户端版本够新吗？

Claude Code 先看版本号：

claude --version

低于 2.1.302 的话先升级。该版本修复了协商新协议但字段缺失导致工具为空的情况，“工具莫名其妙没了”可能属于这一类。

#第 2 步：服务端用的 SDK 是哪个版本？

看你的 MCP 服务端依赖的官方 SDK（TypeScript、Python、Ruby 等）是否已发布支持 2026-07-28 的版本。自己手写协议实现的服务端，重点检查列表类响应有没有返回 ttlMs 和 cacheScope。具体字段要求以规范文档为准。

#第 3 步：临时回退 legacy 协商

MCP_PROTOCOL_NEGOTIATION=legacy claude

这是 Claude Code 更新日志给出的退出开关，按日志原文，默认协商新版本的范围是 claude.ai 连接器、云会话和 Remote Control 连接器，你自己配置的本地 MCP 服务器是否受影响，以官方文档为准。工具恢复，说明服务端和新协议不兼容，应升级服务端；它只适合当临时手段，不要长期依赖。

#第 4 步：检查描述长度

Claude Code 对 MCP 工具描述和服务端 instructions 有长度上限。据更新日志，2.1.296 把默认上限从 2,048 提到 4,096 字符；2.1.300 又把经工具搜索加载的工具描述截断点改为 16,384 字符。描述写得过长的服务端，内容可能被截断，模型看到的不完整。把核心用法放在描述开头。

#第 5 步：远程 MCP 先确认网络通不通

远程 MCP 服务器断线后，2.1.295 之前的版本在无头和 SDK 会话里可能一直不重连。判断是网络问题还是协议问题：

1. 用 curl 直接请求服务端地址，看能否返回。
2. 用 cdnping 在线测速看当前网络到相关 API 的首次连接和往返延迟。
3. 对 Anthropic 一侧，看 /status/anthropic 有没有异常。

网络层的系统排查可以参考Claude Code 连接超时和报错怎么排查：四层网络检查清单和开发者网络自检清单（2026 版）。

#其他几个相关问题

更新后用的是自定义接口，会受影响吗？ 协议版本协商发生在客户端与 MCP 服务器之间，与模型接口地址是两件事。接口地址的配置见Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置。

是客户端坏了还是服务商出故障？ 先分清层次，状态页的读法见怎么看 OpenAI 状态页和 Claude 状态页。

Codex 那边同时也在升级？ 是的，Codex 近期也有版本与模型变动，可以看Codex 10 月 14 日退役旧默认模型，CLI 0.163 新增中途追问和 /config 面板。

#小结与检查表

• 客户端升级到较新版本（Claude Code 至少 2.1.302）。
• 服务端 SDK 升级，列表响应带齐 resultType、ttlMs、cacheScope 等字段。
• 用 MCP_PROTOCOL_NEGOTIATION=legacy 做对照，确认是不是版本问题。
• 工具描述控制长度，关键信息靠前。
• 远程服务器先排除网络问题。

注：MCP 官方博客对版本协商的具体机制没有展开描述，本文只引用了其明确写出的内容；各客户端的最终行为以对应更新日志和官方文档为准。

#参考来源

• The 2026-07-28 Specification（MCP 官方博客，2026-07-28）
• MCP 官方博客（路线图，2026-08-22）
• Claude Code CHANGELOG
• Devin Desktop 更新日志
• Codex 更新日志