トラブルシューティング

セットアップの失敗の大半は4パターンに分類されます:APIキーがサーバーに届いていない、mcp-remoteブリッジが起動しない、リポジトリが解決できない、クライアントがまったく接続できない。症状に合ったセクションを確認してください。

APIキーの問題#

すべてのリクエストはAuthorization: Bearerヘッダーとして送られるAPIキーで認証されます。ツール呼び出しが拒否される場合:

• キーがmgv_プレフィックスで始まっているか確認してください。
• 設定例のmgv_xxxxプレースホルダーを、app.maguyva.aiから取得した実際のキーに置き換えたか確認してください。
• 設定がMAGUYVA_API_KEYからキーを読み込む場合、クライアントが実際に起動する環境でその変数が設定されているか確認してください。~/.zshrcや~/.bashrcに追加したシェルのexportは、シェルを再読み込みしないと反映されません — さらに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 クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合に限ります。

MCP接続の問題#

• 自分のマシンからhttps://maguyva.tools/mcpへの接続をテストしてください — 企業のプロキシやファイアウォールが原因であることがよくあります。
• APIトークンが有効で、期限切れになっていないか確認してください。
• インストールガイドと照らし合わせてクライアント設定を再確認してください — 設定ファイルの場所や形式はクライアントごとに異なります。

修正を確認#

変更後は、エージェントに"接続しているリポジトリはどれですか?"と聞いてみてください — これで接続がエンドツーエンドで確認できます。次にリポジトリについて実際の質問をすれば、接続されたリポジトリのファイルパスと行番号付きの回答が返ってくるはずです。