仓库 →

MCP 集成

MCP（Model Context Protocol）是一个开放协议,把外部程序或 HTTP 服务的「工具」接到 AtomCode,让模型像调用内置工具一样使用它们。从 v4.20.4 起 AtomCode 内置 MCP 客户端,直接复用 Cursor 等同样使用 mcpServers 配置块的生态。

它能做什么

两个配置位置

路径作用域
<项目根>/.mcp.json仅当前项目可见,适合跟代码同仓库
~/.atomcode/mcp.json用户全局,跨所有项目共享

两份可同时存在;同名 server 以项目级为准(覆盖用户级)。仓库根目录的 .mcp.json.example 自带 stdio 与 HTTP 双模板和详细注释,推荐从它开始改。

配置 schema

顶层键固定为 mcpServers(旧键 servers 仍兼容)。每个 server 建议只写一种 transport:

如果同一个 server 同时写了 command 和 url,当前实现会优先按 stdio(command)处理;为避免歧义,对外配置请不要双写。

字符串里支持 ${VAR} 与 ${VAR:-默认值} 的环境变量展开;敏感令牌不要写死,放到环境变量里。disabled: true 可临时关掉某个 server 而不删条目。

stdio 示例(本地子进程)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "timeout_ms": 10000
    }
  }
}

HTTP 示例(远程端点)

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      },
      "timeout_ms": 30000
    }
  }
}

GitHub remote MCP + OAuth

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "auth": {
        "type": "oauth",
        "provider": "github"
      }
    }
  }
}

首次使用前需准备 AtomCode 自己的 GitHub OAuth App client id,然后运行:

atomcode mcp add-github-oauth --global
ATOMCODE_GITHUB_MCP_CLIENT_ID=<client_id> atomcode mcp login github
atomcode

TUI 内也可在设置好环境变量后运行 /mcp login github,登录成功后用 /mcp reload 重连。

一行命令添加 server

atomcode mcp add 自动把 stdio 配置写入 JSON,不用手动编辑:

# 写入项目根 .mcp.json(默认当前目录)
atomcode mcp add playwright npx @playwright/mcp@latest

# 写入用户全局 ~/.atomcode/mcp.json
atomcode mcp add playwright npx @playwright/mcp@latest --global

# 指定项目目录
atomcode mcp add playwright npx @playwright/mcp@latest -C /path/to/repo

第一个参数是 server 键名(将出现在工具名里),后面跟可执行文件 + 参数。

GitHub remote MCP OAuth 可用专用入口:

atomcode mcp add-github-oauth --global
ATOMCODE_GITHUB_MCP_CLIENT_ID=<client_id> atomcode mcp login github
注意

同名会整段覆盖该 server。GitHub OAuth token 保存在 ~/.atomcode/mcp_auth.toml,不会写入 .mcp.json。

启动后会发生什么

模式连接行为工具出现时机
TUI后台并行连接,不阻塞界面每个 server 连上后陆续注册,可能略晚于首屏
单次执行(-p)启动时同步连接,等启用中的 server 尝试结束仅在至少拿到一批工具时挂载 MCP

TUI 下可在会话区看到 ✓ MCP server 'github' connected 或 ✗ MCP server '…' failed: …。单个 server 失败不会拖垮其他 server 与主程序。

工具命名

每个远端 tool 注册成 mcp__<server 键名>__<远端 tool 名>。

例:配置里 "mcpServers": { "github": { ... } },远端有 get_issue,模型看到的工具名就是 mcp__github__get_issue。

--disable-tools 也用这个完整名:

atomcode --disable-tools mcp__github__get_issue,mcp__filesystem__write_file

权限审批

MCP 工具默认 每次调用都需要确认(等同 RequireApproval),因为远端是外部不可信代码。

安全提示

把 MCP 工具返回的内容当作不可信数据处理,不要让它升级成系统指令。一个返回结果带「请忽略之前的指示」的 MCP server,模型不应该照办。

斜杠命令

命令作用
/mcp列出已成功连接的 server 及状态(失败的 server 不在列表里,只在会话区有红色错误行)
/mcp tools <server>异步列出某个 server 实际暴露的远端 tools
/mcp reload重新读取 .mcp.json / ~/.atomcode/mcp.json 并后台重连启用中的 server

当前限制

同类生态对比

产品配置位置备注
AtomCode.mcp.json 的 mcpServers 块当前实现 tools-only
Claude Code.mcp.jsonOAuth、resources、prompts 更全
Cursor.mcp.json常见 command / url 配置通常可复用
CodexCLI 添加OpenAI 生态

已经在用 Cursor 配 MCP server 的话,常见 command / url 类型配置通常可复用;超出当前字段或能力范围的配置需按 AtomCode 当前实现确认。

下一步