トラブルシューティング

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

すべてのリクエストは、Authorization: Bearerヘッダー(クライアントがそれを設定できない場合はX-API-Keyヘッダー)として送られるAPIキーで認証されます。ツール呼び出しが拒否される場合:

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

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

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