指南

为任意 AI 编程 agent 添加 MCP server:Claude Code、Cursor、Codex、Gemini CLI、VS Code 及另外 8 款(2026)

每个 AI 编程 agent 把 MCP server 配置放在哪里?用什么命令添加 server?

大多数 agent 读取一个包含 mcpServers 对象的 JSON 文件:Cursor 是 .cursor/mcp.json,Claude Code 是 .mcp.json,Kiro 是 .kiro/settings/mcp.json,Factory Droid 是 .factory/mcp.json,Junie 是 .junie/mcp/mcp.json。例外情况:VS Code(.vscode/mcp.json 中的 servers 键)、Codex(~/.codex/config.toml 中的 [mcp_servers.NAME] 表)、OpenCode(opencode.json 中的 mcp 键)、Zed(设置中的 context_servers)和 goose(config.yaml 中的 extensions)。Claude Code、Codex、Gemini CLI、Amp 和 Factory Droid 还提供 mcp add 命令。

本文译自英文版指南。命令、配置键与代码均保持原样;如有出入,以英文版为准。 阅读英文原版 → · 其他语言: 日本語 · 한국어 · Español · Português (Brasil)

设置一变,第一时间知道

当这些工具的设置、参数或权限规则发生变化时,每周一封邮件通知你(英文),内容均对照官方文档核实。

快速答案:各 agent 的配置位置

  • Claude Code:远程 server 用 claude mcp add --transport http NAME URL,本地 server 用 claude mcp add NAME -- COMMAND。默认作用域为 local;--scope project 会写入共享的 .mcp.json,--scope user 让该 server 在你的所有项目中可用。
  • Cursor:单个项目用 .cursor/mcp.json 中的 mcpServers,所有项目用 ~/.cursor/mcp.json。
  • OpenAI Codex:codex mcp add NAME -- COMMAND,或在 ~/.codex/config.toml 中添加 [mcp_servers.NAME] 表。
  • Gemini CLI:gemini mcp add NAME COMMAND,默认写入项目的 .gemini/settings.json。加 -s user 则写入 ~/.gemini/settings.json。
  • VS Code(GitHub Copilot):.vscode/mcp.json 中的顶层 servers 对象,或通过 MCP: Open User Configuration 打开的用户配置文件。
  • GitHub 上的 Copilot cloud agent:仓库 Settings,然后 Copilot,然后 MCP servers。粘贴包含 mcpServers 对象的 JSON。
  • OpenCode:opencode.json 中的顶层 mcp 键。
  • Cline:cline_mcp_settings.json 中的 mcpServers。CLI 将其保存在 ~/.cline/data/settings/cline_mcp_settings.json。
  • Amp:amp mcp add NAME -- COMMAND 或 amp mcp add NAME URL,或在 ~/.config/amp/settings.json 或 .amp/settings.json 中设置 amp.mcpServers。
  • Kiro:.kiro/settings/mcp.json(工作区)或 ~/.kiro/settings/mcp.json(用户)中的 mcpServers。
  • Factory Droid:droid mcp add NAME URL_OR_COMMAND --type stdio|http|sse,保存到 ~/.factory/mcp.json。团队在 .factory/mcp.json 中共享 server。
  • Junie:.junie/mcp/mcp.json(项目)或 ~/.junie/mcp/mcp.json(用户)中的 mcpServers。
  • Zed:Zed 设置文件中的 context_servers。
  • goose:~/.config/goose/config.yaml 中 extensions 键下的扩展,或运行 goose configure,然后选择 Add Extension。

本地与远程条目在各处几乎相同

本地 server 是 agent 在你机器上启动、通过 stdio 通信的命令。远程 server 是一个 URL。在大多数 JSON 配置中,本地条目包含 command、args 和 env,远程条目包含 url 和可选的 headers。Cursor、Kiro 和 Junie 都在 mcpServers 下接受这种结构。

.cursor/mcp.json、.kiro/settings/mcp.json 或 .junie/mcp/mcp.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "remote-server": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Codex:~/.codex/config.toml

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

VS Code:.vscode/mcp.json

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

OpenCode:opencode.json

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"]
    },
    "remote-server": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

在 agent 之间复制配置时的陷阱

  • VS Code 在 .vscode/mcp.json 中使用 servers,而不是 mcpServers。从 Cursor 复制的文件需要重命名该键。
  • OpenCode 要求 type 为 local 或 remote,其 command 是一个包含参数的单一数组。
  • Gemini CLI 对 SSE server 使用 url,对 streamable HTTP server 使用 httpUrl。
  • Cline 将没有 type 的远程条目视为旧版 SSE。将 type 设为 streamableHttp 以使用推荐的传输方式。
  • Copilot cloud agent 要求每个 server 都有 tools 数组(用 ["*"] 表示所有工具),且只有名称以 COPILOT_MCP_ 开头的 secret 和变量才会传入配置。
  • Zed 把 server 放在 context_servers 下,没有 Authorization header 的远程 server 会启动标准 MCP OAuth 流程。
  • Codex 使用 TOML 而非 JSON:每个 server 一个 [mcp_servers.NAME] 表。

项目配置、审批与自动批准

  • 在交互式会话中,Claude Code 使用 .mcp.json 中项目作用域的 server 之前会请求批准。
  • .amp/settings.json 中的 server 运行前,Amp 要求先执行 amp mcp approve NAME。全局设置中的 server 无需批准。
  • Kiro 会合并工作区文件和用户文件,以工作区设置为准。autoApprove 列出无需确认即可运行的工具,"*" 批准所有工具。
  • Gemini CLI:在 server 上设置 trust: true 会跳过该 server 的所有工具调用确认。只对你自己控制的 server 使用。
  • Cline:autoApprove 数组列出 Cline 无需询问即可调用的工具。只放安全的工具。
  • Factory Droid:用 droid mcp add 添加的 server 会写入你的用户配置。.factory/mcp.json 中的项目 server 无法用 droid mcp remove 删除,需要直接编辑文件。

检查 server 是否已加载

  • Claude Code:/mcp,也可在这里登录 OAuth server。
  • Codex:TUI 中的 /mcp 显示活动的 server。codex mcp login NAME 用于登录 OAuth server。
  • Gemini CLI:/mcp 显示每个 server 的连接状态。
  • Factory Droid:/mcp 打开交互式管理器。
  • Junie CLI:/mcp 列出 server 及其作用域和状态。
  • Amp:amp mcp doctor。

各 agent 的完整 MCP 设置指南

来源

以下为本指南核对过的官方文档(英文)。 英文版核对日期: 2026-10-18

更多中文指南