疑難排解

大多數的設定失敗可以分成四類：API 金鑰沒有送達伺服器、mcp-remote 橋接程序無法啟動、儲存庫無法解析，或用戶端完全無法連線。請依你遇到的症狀，找到對應的章節逐步排查。

API 金鑰問題#

每個請求都會用你的 API 金鑰進行驗證，並以 Authorization: Bearer 標頭傳送。如果工具呼叫被拒絕：

• 確認你的金鑰是以 mgv_ 開頭。
• 確認你已經把設定範例中的 mgv_xxxx 佔位符，換成從 app.maguyva.ai 取得的真實金鑰。
• 如果你的設定是從 MAGUYVA_API_KEY 讀取金鑰，請確認這個變數確實設定在你的用戶端實際啟動的那個環境中。加到 ~/.zshrc 或 ~/.bashrc 的 shell export，只有在重新載入 shell 之後才會生效——而 GUI 應用程式甚至可能完全不會繼承這些設定。如果不確定，直接把金鑰放進設定檔的 env 區塊裡最保險。
• 確認金鑰沒有過期或被撤銷。

mcp-remote 橋接問題#

大多數已建檔的用戶端設定，都會啟動一個本機橋接程序，把 stdio MCP 流量轉發到遠端伺服器：

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

如果伺服器完全沒有出現在你的用戶端裡，或是出現後立刻斷線：

• 確認 npx 存在於你的 PATH 中——橋接程序需要一個可正常運作的 Node.js 安裝環境。在終端機執行 npx -y mcp-remote --help，確認它可以啟動。
• 檢查你用戶端的 MCP 設定語法——某些用戶端在 JSON 檔案格式錯誤時，會靜默失敗，不會顯示任何錯誤。
• 很多用戶端其實根本不需要橋接程序。Claude Code 使用 Maguyva 外掛（/plugin install maguyva@maguyva），而 Cursor、VS Code、Windsurf 與 Zed 則是原生支援以 Bearer 標頭連接遠端伺服器（Zed 是透過 context_servers）。橋接程序只給那些不原生支援遠端標頭的用戶端使用，例如 Claude Desktop 那種僅支援 OAuth 連接器的用戶端。

找不到儲存庫#

• 確認該儲存庫已在 app.maguyva.ai 中連接並完成索引。
• 檢查格式："owner/repo" 指向預設分支，"owner/repo:branch" 指向特定分支（例："owner/repository:develop"）。
• 確認您的帳號對該儲存庫具有存取權。
• 使用 repository_context(action="info", repository="...") 檢查儲存庫解析；僅當您的 MCP 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時，才可省略 repository 參數。

MCP 連線問題#

• 從你的機器測試對 https://maguyva.tools/mcp 的連線——公司代理伺服器與防火牆通常是常見的元兇。
• 確認你的 API 權杖有效且尚未過期。
• 對照你用戶端的 安裝指南，重新檢查設定內容——不同用戶端的設定檔位置與格式各不相同。

驗證修復結果#

做完任何變更之後，問你的代理 "我目前連接了哪些儲存庫？"——這樣就能端到端驗證連線是否正常。接著再問一個關於你儲存庫的真實問題；你應該會看到附有檔案路徑與行號、來自你已連接儲存庫的答案。