# トラブルシューティング

Canonical source: https://maguyva.ai/ja/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

よくあるMaguyvaのセットアップ失敗を解決: APIキーの問題、@maguyva/mcp ブリッジの問題、リポジトリの検索、接続エラー。

### APIキーの問題

- キーがmgv_プレフィックスで始まっているか確認してください。
- 設定例のmgv_xxxxプレースホルダーを、app.maguyva.aiから取得した実際のキーに置き換えたか確認してください。
- 設定がMAGUYVA_API_KEYからキーを読み込む場合、クライアントが実際に起動する環境でその変数が設定されているか確認してください。~/.zshrcや~/.bashrcに追加したシェルのexportは、シェルを再読み込みしないと反映されず、GUIアプリは全く継承しないこともあります。迷ったら、キーを設定に直接書いてください。ネイティブのリモート設定ではAuthorizationヘッダー(Bearerの後にキー)に、@maguyva/mcpブリッジの設定ではenvブロックに書きます。
- キーの有効期限が切れていないか、取り消されていないか確認してください。

### @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 クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合に限ります。

### MCP接続の問題

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

### 修正を確認

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