How do I troubleshoot apiキーの問題?

キーがmgv_で始まっているか確認するキーが環境に正しく設定されているか確認するキーの有効期限が切れていないか確認する

How do I troubleshoot リポジトリが見つからない?

app.maguyva.aiでリポジトリが接続されているか確認する owner/repo形式が正しいか確認するリポジトリへのアクセス権があるか確認する

How do I troubleshoot mcp接続の問題?

npxがPATHに含まれているか確認する APIトークンが有効で、期限切れでないか確認する https://maguyva.tools/mcpへの接続をテストするクライアントのMCP設定構文を確認する

Maguyva MCPのセットアップが機能しているか、どう確認すればよいですか?

接続後、エージェントにさまざまな検索モードを試すプロンプトを投げてみてください: "接続しているリポジトリはどれですか?" (接続が機能しているかを確認する); "このコードベースでは認証がどう処理されていますか?" (セマンティック検索をテストする); "データベースを呼び出しているすべての関数を見つけて" (依存関係検索をテストする); "UserServiceクラスは何に依存していますか?" (シンボルルックアップをテストする)。接続済みリポジトリのファイルパスと行番号付きの結果が返ってくるはずです。

Maguyva MCPのリクエストでリポジトリを指定するには?

MCP クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合は、リポジトリを省略します。それ以外では、既定ブランチには "owner/repo"（例："owner/repository"）、特定のブランチには "owner/repo:branch"（例："owner/repository:develop"）を使用します。

インストールガイド

Q: How do I troubleshoot apiキーの問題?

キーがmgv_で始まっているか確認する キーが環境に正しく設定されているか確認する キーの有効期限が切れていないか確認する

5分足らずで使い始められます。このガイドにはClaude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot、Windsurfを含む24件のMCPクライアント向けセットアップが含まれています。

前提条件: app.maguyva.aiから取得したAPIキーと、接続済みのGitHubリポジトリが必要です。

環境のセットアップ#

まず、API キーを環境変数に設定します。MCP クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合は repository を省略し、それ以外では明示的に渡します。

macOS/Linux (Bash/Zsh)#

# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)#

# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

mgv_xxxxを、app.maguyva.aiから取得した実際のAPIキーに置き換えてください。

クライアント設定#

以下から使用するMCPクライアントを選んで、具体的なセットアップ手順を確認してください。

互換性に関する注記: Maguyvaは標準のMCPを使用しています。MCPに対応したクライアントであれば、まだ公式のセットアップガイドを用意していなくても、同じサーバーに接続できます。

Claude Code

Claude Codeのマーケットプレイスから、Maguyvaプラグインをインストールしてください:

Maguyvaのマーケットプレイスを追加してから、プラグインをインストールしてください（各コマンドはClaude Code内で実行します）:

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

この方法ではユーザーアカウント単位でインストールされます。チームで使う場合は、両方のコマンドに--scope projectを追加すると、プラグインがリポジトリの.claude/settings.jsonにコミットされ、チームメイトにも自動的に反映されます。

このプラグインはMAGUYVA_API_KEY環境変数を使って認証します。シェルで次のように設定してください:

export MAGUYVA_API_KEY=mgv_xxxx

プロジェクトごとのdirenv（.envrc）の利用を推奨します。APIキーはリポジトリ単位で発行されるため、プロジェクトごとに値を設定しておくと、それぞれのアクセス範囲に一致します。1つのキーですべての作業をカバーできるなら、グローバルなシェルのexportでも問題ありません。

手動設定（.mcp.json）— 上級者向け

.mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Claude CodeのMCPドキュメント →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Claude Desktopの設定ファイルに追加してください:

claude_desktop_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Claude Desktopは、Settings経由のOAuth「コネクタ」としてのみリモートサーバーに対応しており、claude_desktop_config.json内のヘッダー認証エントリとしては対応していません。そのため、ここではmcp-remoteブリッジ（Node.js / npxが必要）を使用します。

Claude DesktopのMCPドキュメント →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

プロジェクトルートの.cursor/mcp.jsonに追加してください:

.cursor/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

CursorのMCPドキュメント →

VS Code / GitHub Copilot

プロジェクトの.vscode/mcp.json（またはユーザー設定）に追加してください:

.vscode/mcp.json

{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

VS Code / GitHub CopilotのMCPドキュメント →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

WindsurfのMCP設定に追加してください:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

WindsurfのMCPドキュメント →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Codex CLIの設定（~/.codex/config.toml）に追加してください:

.codex/config.toml

[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

CodexのMCPドキュメント →

GitHub Copilot CLI

.copilot/mcp-config.jsonに追加してください:

.copilot/mcp-config.json

{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

GitHub Copilot CLIのMCPドキュメント →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Gemini CLIの設定（~/.gemini/settings.json）に追加してください:

settings.json

{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Gemini CLIのMCPドキュメント →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

ClineのMCP設定に追加してください:

cline_mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

このクライアントはまだ、カスタム認証ヘッダー付きのリモートMCPサーバーに対応していないため、mcp-remoteブリッジ（Node.js / npxが必要）経由で接続します。Maguyva自体はすべてリモートで動作しており、ローカルで動くのはこのブリッジのみです。

ClineのMCPドキュメント →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Roo CodeのMCP設定に追加してください:

mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Roo CodeのMCPドキュメント →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %AppData%\goose\config.yaml
Linux: ~/.config/goose/config.yaml

Gooseの設定に追加してください:

config.yaml

extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

GooseのMCPドキュメント →

LM Studio

LM StudioではAgent設定からMCPサーバーを利用できます。Settings → Agent → MCP Serversで新しいMCPサーバーを追加し、標準のmcpServers JSON形式を使用してください。LM Studioはstdio経由でMCPサーバーに接続します。ドキュメントを見る →

Continue

macOS: ~/.continue/config.json
Windows: %UserProfile%\.continue\config.json
Linux: ~/.continue/config.json

Continueの設定（~/.continue/config.json）に追加してください:

config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

ContinueのMCPドキュメント →

Amazon Q Developer

macOS: ~/.aws/amazonq/mcp.json
Windows: %UserProfile%\.aws\amazonq\mcp.json
Linux: ~/.aws/amazonq/mcp.json

Amazon QのMCP設定に追加してください:

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Amazon Q DeveloperのMCPドキュメント →

PyCharm

プロジェクトルートの.ai/mcp/mcp.jsonに追加するか、Settings > Tools > AI Assistant > MCPに貼り付けてください:

.ai/mcp/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

PyCharmのMCPドキュメント →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Zedの設定（~/.config/zed/settings.json）に追加してください:

settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

ZedのMCPドキュメント →

Trae

プロジェクトルートの.trae/mcp.jsonに追加してください:

.trae/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

TraeのMCPドキュメント →

OpenCode

プロジェクトルートのopencode.jsonに追加してください:

opencode.json

{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

OpenCodeのMCPドキュメント →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

BoltAIのMCP設定に追加してください:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

BoltAIのMCPドキュメント →

LibreChat

LibreChatの設定に追加してください:

librechat.yaml

mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

LibreChatのMCPドキュメント →

Antigravity

macOS: ~/.gemini/antigravity/mcp_config.json
Windows: %UserProfile%\.gemini\antigravity\mcp_config.json
Linux: ~/.gemini/antigravity/mcp_config.json

AntigravityのMCP設定に追加してください:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

AntigravityのMCPドキュメント →

Claude Cowork

Claude Coworkは、他のAnthropicクライアントと同じMCP形式を使用します:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxxを、app.maguyva.aiから取得したAPIキーに置き換えてください。

Claude CoworkのMCPドキュメント →

ChatGPT

ChatGPTはBusiness、Enterprise、Eduプランで、Settings → Apps → CreateからリモートMCPサーバーに対応しています。リモートHTTPSエンドポイントが必要です。ChatGPTはローカルstdioサーバーには対応していません。セットアップはOpenAIのMCPガイドを参照してください。ドキュメントを見る →

Warp

WarpはAgent ModeでMCPサーバーに対応しています。設定はWarp UI（Settings → Agent Mode → MCP Servers）で管理され、Warp Drive経由で同期されます。サーバー追加時に標準のmcpServers JSONを貼り付けてください。ドキュメントを見る →

Maguyvaは標準のMCPを使用しています。上記に専用ガイドがなくても、プロトコルに対応するクライアントであれば接続できます。現在24件のクライアントがドキュメント化されており、随時追加されています。

セットアップを検証する#

接続後、エージェントにいくつか質問してみてください:

"接続しているリポジトリはどれですか?" — 接続が機能しているかを確認する
"このコードベースでは認証がどう処理されていますか?" — セマンティック検索をテストする
"データベースを呼び出しているすべての関数を見つけて" — 依存関係検索をテストする
"UserServiceクラスは何に依存していますか?" — シンボルルックアップをテストする

接続済みリポジトリのファイルパスと行番号付きの結果が返ってくるはずです。返ってこない場合は、下のtroubleshooting sectionを確認してください。

リポジトリ形式#

リポジトリを指定する際は:

ブランチ指定あり: "owner/repo:branch" (e.g., "owner/repository:develop")
デフォルトブランチ: "owner/repo"

ヒント：repository_context(action="info", repository="...") でリポジトリの解決を確認します。v3 サーバーはステートレスなので、リポジトリの上書きは 1 回の呼び出しだけに適用されます。

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

APIキーの問題#

キーがmgv_で始まっているか確認する
キーが環境に正しく設定されているか確認する
キーの有効期限が切れていないか確認する

リポジトリが見つからない#

app.maguyva.aiでリポジトリが接続されているか確認する
owner/repo形式が正しいか確認する
リポジトリへのアクセス権があるか確認する

MCP接続の問題#

npxがPATHに含まれているか確認する
APIトークンが有効で、期限切れでないか確認する
https://maguyva.tools/mcpへの接続をテストする
クライアントのMCP設定構文を確認する

次のステップ#

MCP APIリファレンス - 完全なAPIドキュメント
仕組み - コンテキスト最適化を理解する
トラブルシューティング - セットアップと接続の問題を解決する