MCP Integration

MCP (Model Context Protocol) is an open protocol that plugs the "tools" exposed by external programs or HTTP services into AtomCode, so the model can call them like built-in tools. Since v4.20.4, AtomCode ships a built-in MCP client and re-uses the same mcpServers configuration block as Cursor and others.

What it enables

• Operate GitHub, GitLab, Jira, and other external services via official MCP servers
• Connect to Postgres / MySQL / DuckDB and other databases
• Use community servers for the filesystem, Playwright browser, Slack messages, and more
• Expose your team's domain-specific tools to the model without modifying atomcode source

Two config locations

Both can coexist; same-named servers prefer the project-level entry (it overrides the user-level one). The repo's .mcp.json.example ships heavily-commented stdio + HTTP templates — start from there.

Config schema

The top-level key is fixed at mcpServers (the legacy servers key still works). Each server should pick one transport:

• stdio: command (required) + optional args, env, timeout_ms, disabled
• HTTP: url (required) + optional headers, auth, timeout_ms, disabled

If a server has both command and url, the current implementation treats it as stdio (command). To avoid ambiguity, don't write both.

Strings support ${VAR} and ${VAR:-default} environment expansion; never hard-code sensitive tokens — keep them in env vars. disabled: true temporarily turns off a server without removing the entry.

stdio example (local subprocess)

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

HTTP example (remote endpoint)

{
  "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"
      }
    }
  }
}

Before first use, you need AtomCode's own GitHub OAuth App client id, then run:

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

Inside the TUI you can also set the env var and run /mcp login github; after a successful login, /mcp reload reconnects.

One-line server add

atomcode mcp add writes the stdio config to JSON for you — no hand-editing required:

# Write to project-root .mcp.json (current directory by default)
atomcode mcp add playwright npx @playwright/mcp@latest

# Write to user-global ~/.atomcode/mcp.json
atomcode mcp add playwright npx @playwright/mcp@latest --global

# Pin a specific project directory
atomcode mcp add playwright npx @playwright/mcp@latest -C /path/to/repo

The first positional is the server key name (which will appear in tool names); the rest is the executable + args.

For GitHub remote MCP OAuth there's a dedicated entry:

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

What happens at startup

In the TUI you'll see ✓ MCP server 'github' connected or ✗ MCP server '…' failed: … in the session area. A single server failure does not break other servers or the main program.

Tool naming

Each remote tool is registered as mcp__<server-key>__<remote-tool-name>.

Example: with "mcpServers": { "github": { ... } } and a remote get_issue tool, the model sees the tool name mcp__github__get_issue.

--disable-tools uses the full name too:

atomcode --disable-tools mcp__github__get_issue,mcp__filesystem__write_file

Permission approval

MCP tools default to per-call confirmation (equivalent to RequireApproval) because the remote is external, untrusted code.

• Press Y — allow once
• Press A — allow this tool for the current session (resets next launch; never persisted)
• Press N — deny this call

Slash commands

Current limits

• Only MCP's tools capability is supported; resources / prompts / OAuth / roots / elicitation are not yet implemented
• HTTP servers don't have exponential-backoff reconnects, and stdio child processes don't auto-restart on exit — use /mcp reload to reconnect manually
• tools/list list_changed notifications don't trigger a dynamic refresh
• Tool results only consume text content blocks; image / resource blocks are currently ignored
• [A] Always applies only within the current session; it is never written to a config file

Ecosystem comparison

If you already use Cursor's MCP setup, common command / url configs are usually reusable; anything outside AtomCode's current fields or capabilities needs verification.

Next steps

• The .mcp.json.example at the repo root — heavily-commented stdio + HTTP templates
• Configuration — overall config overview
• Slash Commands — full command list including the /mcp family