部落格 / 開發工具

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 更新日誌