疑難排解

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

每個請求都會用你的 API 金鑰進行驗證，並以 Authorization: Bearer 標頭傳送；若用戶端無法設定該標頭，也可以用 X-API-Key 標頭。如果工具呼叫被拒絕：

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

若用戶端使用 @maguyva/mcp 橋接程式，它會啟動一個本機處理程序，連接到 Maguyva 的遠端伺服器：

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

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

• 確認 npx 存在於你的 PATH 中——橋接程序需要一個可正常運作的 Node.js 安裝環境。在終端機執行 npx -y @maguyva/mcp --help，確認它可以啟動。
• 檢查你用戶端的 MCP 設定語法——某些用戶端在 JSON 檔案格式錯誤時，會靜默失敗，不會顯示任何錯誤。
• 很多用戶端其實根本不需要橋接程序。Claude Code 使用 Maguyva 外掛（/plugin install maguyva@maguyva），而 Cursor、VS Code、Devin Desktop 與 Zed 則是原生支援以 Bearer 標頭連接遠端伺服器（Zed 是透過 context_servers）。橋接程序適用於無法從設定檔送出該標頭的用戶端，例如 Claude Desktop：它的 claude_desktop_config.json 只會啟動本機伺服器。Claude Desktop 的自訂連接器可以送出 authorization 請求標頭，但請求標頭目前仍在測試階段，只開放給少數組織。

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

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

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