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_ 前缀开头 检查密钥是否已在你的环境中正确设置 确认密钥没有过期

Q: How do I troubleshoot mcp 连接问题?

确认 npx 在你的 PATH 中可用 检查你的 API 令牌是否有效、是否已过期 测试到 https://maguyva.tools/mcp 的连通性 检查你的客户端 MCP 配置语法

5 分钟内即可上手运行。本指南包含 24 个 MCP 客户端的配置说明，包括 Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot、和 Windsurf 等等。

前置条件：你需要从 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 环境变量进行身份验证。请在你的 shell 中设置它：

export MAGUYVA_API_KEY=mgv_xxxx

建议按项目使用 direnv（.envrc）——由于密钥是按仓库划分范围的，按项目设置值能更好地匹配每个项目的访问权限。如果一个密钥就能覆盖你的所有工作，用全局 shell 导出也可以。

手动配置（.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 中，使用标准的 mcpServers JSON 格式添加一个新的 MCP 服务器。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 的用户界面管理（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 服务器是无状态的，因此仓库覆盖仅适用于一次调用。

故障排查#

API 密钥问题#

确认你的密钥以 mgv_ 前缀开头
检查密钥是否已在你的环境中正确设置
确认密钥没有过期

找不到仓库#

确认该仓库已在 app.maguyva.ai 中连接
检查 owner/repo 格式是否正确
确认你有权限访问该仓库

MCP 连接问题#

确认 npx 在你的 PATH 中可用
检查你的 API 令牌是否有效、是否已过期
测试到 https://maguyva.tools/mcp 的连通性
检查你的客户端 MCP 配置语法

后续步骤#

MCP API 参考 - 完整的 API 文档
工作原理 - 了解上下文优化机制
故障排查 - 解决配置和连接问题