MCP 錯誤 -32601：方法未找到 - 2026 年完整解決與故障排除指南

主要要點

• MCP 錯誤 -32601「方法未找到」 是一個標準的 JSON-RPC 2.0 錯誤，當客戶端請求一個 MCP 伺服器未實作或未在其功能中聲明的方法時會發生此錯誤。
• 主要原因包括：選擇性方法探查（resources/list、prompts/list、elicit）、客戶端與伺服器 SDK 之間的版本不符，以及不完整的功能聲明。
• 大多數情況是良性且預期的；持續性錯誤通常透過使用官方 MCP Inspector 並調整實作來解決。
• 常見於 Claude Desktop、Cursor、Continue.dev，以及使用 FastMCP、Spring AI 或 McpSharp 建立的客製伺服器。

了解 MCP 方法未找到錯誤

模型上下文協定 (MCP) 使用 JSON-RPC 2.0 透過各種傳輸方式，標準化了 AI 客戶端（Claude、Cursor 等）與外部伺服器之間的溝通（針對工具、資源和提示）。

典型的錯誤回應看起來像這樣：

{
  "jsonrpc": "2.0",
  "id": 19,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

這表示請求的方法（例如 tools/call、resources/list、prompts/list 或與 elicitation 相關的方法）伺服器未知。與連線或解析錯誤不同，傳輸層通常會成功——問題出現在協定層級。

社群報告和 GitHub 問題顯示，此錯誤經常出現在功能探索期間，或當客戶端假設的支援範圍比伺服器實際提供的更廣泛時。

常見原因

對近期問題（2025–2026）的分析指出了以下引發因素：

• 選擇性方法未實作：MCP 伺服器不需要支援所有功能。像 Claude Desktop 這樣的客戶端經常探查 resources/list、prompts/list 或 elicitation 方法，如果伺服器未支援就會觸發 -32601 錯誤。
• 功能聲明遺漏：伺服器的 initialize 回應沒有正確聲明支援的功能，導致客戶端呼叫未支援的方法。
• SDK 與版本不符：不同版本的 @modelcontextprotocol/sdk、FastMCP、Spring AI MCP 或 McpSharp 造成不相容。Java 用戶經常透過改用 JDK 21 來解決此問題。
• IDE/客戶端特定行為：Cursor 代理聊天可能會在方法錯誤之外報告「沒有可用的 MCP 資源」。Claude 的記錄中會出現重複的「方法未找到: resources/list」。
• Elicitation 請求：FastMCP 及類似的框架在用戶輸入 elicitation 時，如果客戶端不完全支援，會拋出 McpError。
• 客製或最小實作：手動編寫的伺服器如果沒有適當的錯誤處理或完整的基礎功能支援（initialize、tools/list、tools/call），在實際客戶端下會失敗。
• 傳輸/代理問題：在 Docker、ngrok 或 inspector 代理設定中，路由問題可能表現為方法錯誤。

逐步故障排除與解決方法

1. 使用 MCP Inspector 進行診斷

官方工具是驗證您伺服器最快的方式：

# Node.js / TypeScript
npx @modelcontextprotocol/inspector "node your-server.js"

# Python
uvx mcp-inspector "python your_server.py"

檢視器會顯示功能，讓你互動式地測試方法，並明確揭露哪些方法返回 -32601。若某方法在此失敗，代表伺服器未實作該方法。

2. 正確檢查並宣告功能

在 initialize 握手階段，伺服器必須返回準確的功能。範例結構：

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": false,
    "prompts": false
  }
}

請明確將不支援的功能設為 false 或省略，以避免不必要的探查。

3. 協調版本與相依性

• 更新客戶端和伺服器至匹配的 MCP SDK 版本。
• 對於 Java/Spring AI：將 JAVA_HOME 設為 JDK 21+ 並清除緩存。
• 對於 Cursor/Claude：更新後重新啟動應用程式並刷新 MCP 配置。
• 若近期版本引入不相容問題，請退回先前穩定版本（例如舊報告中的 Cursor 0.45）。

4. 徹底檢查紀錄

• 伺服器端：確認接收到的確切方法名稱及其路由方式。
• 客戶端：審查 Claude 紀錄（macOS 上的 ~/Library/Logs/Claude/）、Cursor 擴充功能輸出或 Continue.dev 控制台。
• 尋找序列：成功的 initialize 後接續失敗的選擇性方法呼叫。

5. 處理選擇性與特殊情況方法

• 在客戶端程式碼中，盡可能將選擇性方法的 -32601 視為非致命錯誤。
• 對於需要大量引導的工具：實作優雅的備用方案，或若目標客戶端（例如 Gemini CLI 或特定 Cursor 模式）缺乏支援，則停用該功能。
• 在自訂伺服器中：始終以適當的 JSON-RPC 錯誤格式回應，而非崩潰或超時。

進階技巧與陷阱

• 資源與提示探查：許多伺服器會紀錄無害的「Method not found: resources/list」——若核心工具功能正常，請忽略這些訊息。
• Docker 與遠端設置：驗證埠轉送、健康檢查，並確保 POST 請求到達正確處理器。405 錯誤有時伴隨 -32601 出現。
• 測試策略：始終先使用 MCP Inspector 測試，然後使用多個客戶端（Claude Desktop、Cursor、Continue.dev）。透過 curl 進行直接 JSON-RPC 呼叫以進行低階驗證。
• 性能相關的模仿：長時間運行的工具呼叫與超時（在 Spring AI 中常見）可能在下游以方法錯誤形式出現。
• 最小可行伺服器：至少實作 initialize、tools/list、tools/call 和 ping。為每個接收請求添加穩健的紀錄。

預防最佳實踐

• 嚴格遵循最新的 MCP 規範處理錯誤碼與能力回應。
• 盡可能使用官方 SDK，而非從頭自行實作。
• 在生產伺服器中包含完整的記錄機制與版本協商功能。
• 定期監控 modelcontextprotocol GitHub 組織的更新與重大變更。
• 徹底測試能力探索功能——這能預防實際使用中大部分的 -32601 問題。

明確公告能力並妥善處理可選方法的開發者，通常回報的支援問題數量明顯較少。

結論

MCP -32601「方法未找到」錯誤通常是協議可選功能的正常行為，而非重大故障。透過 MCP Inspector 進行系統性診斷、適當的能力宣告以及版本一致性，幾乎能解決所有案例。

隨著生態系統在 2026 年持續成熟，請保持您的 MCP 伺服器與客戶端為最新版本。對於棘手問題，可在相關 GitHub 儲存庫或社群論壇分享您的伺服器能力 JSON、詳細方法記錄與客戶端版本，以獲得更快的社群協助。

實施這些實踐方法，可建立更穩健且相容的 MCP 整合方案。