故障排查

大多数配置故障可以归为四类：API 密钥没有传到服务器、mcp-remote 桥接程序没能启动、仓库无法解析，或者客户端完全无法连接。请找到和你的症状对应的章节逐一排查。

API 密钥问题#

每个请求都会通过你的 API 密钥进行身份验证，该密钥以 Authorization: Bearer 请求头的形式发送。如果工具调用被拒绝：

• 确认你的密钥以 mgv_ 前缀开头。
• 检查你是否已经把配置示例中的 mgv_xxxx 占位符替换成了从 app.maguyva.ai 获取的真实密钥。
• 如果你的配置是从 MAGUYVA_API_KEY 读取密钥的，请确认该变量在你的客户端实际启动的环境中已经设置好。添加到 ~/.zshrc 或 ~/.bashrc 中的 shell 导出，只有在重新加载 shell 之后才会生效——而且 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 令牌是否有效、是否已过期。
• 对照 安装指南 中你所用客户端的说明，重新检查客户端配置——配置文件的位置和格式因客户端而异。

验证修复结果#

每次改动之后，都问一下你的智能体 "我连接了哪些仓库？"——这样能端到端地验证连接是否正常。然后再问一个关于你仓库的真实问题；你应该会看到来自已连接仓库的、带有文件路径和行号的答案。