--- title: "MCP 工具不显示怎么办：2026-07-28 新规范下的 5 步排查（2026 年 10 月）" description: "升级客户端后 MCP 工具列表变空，多半是协议版本切到了 2026-07-28。按版本、服务端、legacy 回退、描述长度、网络五步排查，附 Claude Code 对应版本。" url: https://cdnping.org/blog/mcp-2026-07-28-spec-upgrade-tools-missing language: zh-CN published: 2026-10-18 category: "开发工具" tags: ["MCP","Claude Code","Codex","Devin Desktop","协议升级"] source: cdnping.org license: Free to quote and summarize with a link to the url above. --- # MCP 工具不显示怎么办：2026-07-28 新规范下的 5 步排查（2026 年 10 月） 升级 Claude Code 或其他客户端之后，如果 MCP 工具突然不显示，先怀疑协议版本：2026-07-28 版 MCP 规范正在成为各客户端的默认协商版本，而旧版服务端或没完全实现新字段的服务端，可能被连上却拿不到工具。最快的验证办法是设置 `MCP_PROTOCOL_NEGOTIATION=legacy` 退回旧协商（更新日志写明该开关用于 claude.ai 连接器、云会话和 Remote Control 连接器的协商），工具回来了，问题多半出在版本上。本文以 2026 年 10 月为时间口径，下面的版本号以各项目公开的更新日志为准。 ## 这次到底改了什么？ MCP 官方博客在 2026 年 7 月 28 日发布了 [2026-07-28 版规范](https://blog.modelcontextprotocol.io/posts/2026-07-28/)，8 月 22 日又发布了新路线图（见 [MCP 官方博客](https://blog.modelcontextprotocol.io/)）。与排查相关的变化有这几项（据该博客文章）： - 核心改为无状态：`initialize`/`initialized` 握手和 `Mcp-Session-Id` 头被取消，每个请求自带协议版本、客户端信息和能力。 - 新增可选的 `server/discover`，想提前了解服务端能力的客户端可以调用，但不是必须。 - 服务端需要用户输入时，返回 `resultType: "input_required"`，客户端带着答案重试。 - `tools/list`、`prompts/list`、`resources/list`、`resources/read` 的响应带有 `ttlMs` 和 `cacheScope`，供客户端决定缓存策略。 握手没了。2.1.302 的修复说明，服务端若协商了新版本却缺少这些字段，会出现工具为空的情况。 ## 各客户端现在是什么状态？ | 客户端 | 与此相关的变化 | 来源 | |---|---|---| | Claude Code 2.1.295 | claude.ai 连接器默认协商 2026-07-28，`MCP_PROTOCOL_NEGOTIATION=legacy` 可退出；修复远程 MCP 断线超过 15 秒后不重连 | [Claude Code CHANGELOG](https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md) | | Claude Code 2.1.299 | 云会话和 Remote Control 连接器同样默认协商新版本 | 同上 | | Claude Code 2.1.302 | 修复服务端协商 2026-07-28 但省略 `resultType`、`ttlMs` 或 `cacheScope` 时，工具为空或调用全部失败 | 同上 | | Devin Desktop（原 Windsurf）3.10.67，2026 年 10 月 12 日 | 支持连接 2026-07-28 版 MCP 服务器（`server/discover`，无 `initialize`） | [Devin 更新日志](https://docs.devin.ai/desktop/changelog) | | Codex CLI 0.158.0，2026 年 9 月 28 日 | 支持需要预注册 OAuth client secret 的 MCP 服务器，通过 `codex mcp add` 配置 | [Codex 更新日志](https://learn.chatgpt.com/docs/changelog) | 注意 Codex 这一条是 OAuth 方面的能力，不是协议版本切换，别把两件事混在一起排查。 ## 工具不显示时怎么一步步排查？ ### 第 1 步：客户端版本够新吗？ Claude Code 先看版本号： ```bash claude --version ``` 低于 2.1.302 的话先升级。该版本修复了协商新协议但字段缺失导致工具为空的情况，“工具莫名其妙没了”可能属于这一类。 ### 第 2 步：服务端用的 SDK 是哪个版本？ 看你的 MCP 服务端依赖的官方 SDK（TypeScript、Python、Ruby 等）是否已发布支持 2026-07-28 的版本。自己手写协议实现的服务端，重点检查列表类响应有没有返回 `ttlMs` 和 `cacheScope`。具体字段要求以[规范文档](https://blog.modelcontextprotocol.io/posts/2026-07-28/)为准。 ### 第 3 步：临时回退 legacy 协商 ```bash 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](/status/anthropic) 有没有异常。 网络层的系统排查可以参考[Claude Code 连接超时和报错怎么排查：四层网络检查清单](/blog/claude-code-connection-troubleshooting)和[开发者网络自检清单（2026 版）](/blog/developer-network-self-check-2026)。 ## 其他几个相关问题 **更新后用的是自定义接口，会受影响吗？** 协议版本协商发生在客户端与 MCP 服务器之间，与模型接口地址是两件事。接口地址的配置见[Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置](/blog/configure-custom-api-endpoint-claude-code-codex)。 **是客户端坏了还是服务商出故障？** 先分清层次，状态页的读法见[怎么看 OpenAI 状态页和 Claude 状态页](/blog/how-to-read-ai-status-pages)。 **Codex 那边同时也在升级？** 是的，Codex 近期也有版本与模型变动，可以看[Codex 10 月 14 日退役旧默认模型，CLI 0.163 新增中途追问和 /config 面板](/blog/codex-model-retirement-cli-0-163)。 ## 小结与检查表 - 客户端升级到较新版本（Claude Code 至少 2.1.302）。 - 服务端 SDK 升级，列表响应带齐 `resultType`、`ttlMs`、`cacheScope` 等字段。 - 用 `MCP_PROTOCOL_NEGOTIATION=legacy` 做对照，确认是不是版本问题。 - 工具描述控制长度，关键信息靠前。 - 远程服务器先排除网络问题。 注：MCP 官方博客对版本协商的具体机制没有展开描述，本文只引用了其明确写出的内容；各客户端的最终行为以对应更新日志和官方文档为准。 ## 参考来源 - [The 2026-07-28 Specification（MCP 官方博客，2026-07-28）](https://blog.modelcontextprotocol.io/posts/2026-07-28/) - [MCP 官方博客（路线图，2026-08-22）](https://blog.modelcontextprotocol.io/) - [Claude Code CHANGELOG](https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md) - [Devin Desktop 更新日志](https://docs.devin.ai/desktop/changelog) - [Codex 更新日志](https://learn.chatgpt.com/docs/changelog)