MCP

Connect an Atlas workspace to MCP clients such as Claude Code, Cursor, and Codex using a workspace API key. Manage projects, run the platform agent, and work with exported APIs, scoped to one workspa

---

Atlas Platform MCP (Alpha)

Atlas Platform MCP connects a workspace to Model Context Protocol clients — including Claude Code, Cursor, Codex, and other compatible tools — using a workspace API key. This is an alpha integration: the tool surface and endpoint may change. It can currently be enabled per workspace on request.

When to use MCP

• Manage projects from a coding tool. Create, inspect, update, clone, or share Atlas projects without leaving Claude Code, Cursor, or Codex.

• Drive graph building from an assistant. Ask the platform agent to construct or edit a graph in one turn while watching it build live in the browser.

• Work with exported APIs alongside code. List, rename, enable, disable, or remove exported project APIs from the same session where you're writing the code that calls them.

What MCP can do

• Projects — create, list, inspect, update, clone, delete, and share workspace projects.

• Platform agent — run a one-shot agent turn on a project to build or edit a graph. In this version the agent's turns are stateless: it can construct graphs but cannot run nodes. A browser open on the same project can watch the graph build live.

• Exported APIs — export a project as an API, then list, rename, enable, disable, or remove it.

• Project provenance — projects created through MCP are labeled "via MCP." The list_projects and get_project tools expose a createdViaMcp field, and workspaces with MCP access can filter their Projects page by MCP origin.

Every MCP tool enforces the same permission matrix as the web app and runs with the same permissions as the API key's owner. One key authenticates one workspace — use a separate key per workspace.

Setting up MCP

1. Create and load a workspace API key

Create a workspace API key (atk_…) from workspace settings → API Keys, and copy it when it's shown — the key is only displayed once.

Load it into your shell with a hidden prompt so it never appears in shell history, then launch your MCP client from that same shell:

read -rsp 'Atlas workspace API key: ' ATLAS_API_KEY
printf '\n'
export ATLAS_API_KEY

2. Point your client at the MCP endpoint

MCP is a streamable-HTTP endpoint. Send the key as a bearer token on every request:

https://mcp.dev.atlas.design/mcp

3. Connect Claude Code

Register the server after loading the key. The single-quoted header preserves the ${ATLAS_API_KEY} environment reference in Claude's saved configuration instead of storing the key itself:

claude mcp add --transport http atlas https://mcp.dev.atlas.design/mcp \
  --header 'Authorization: Bearer ${ATLAS_API_KEY}'

Run claude — the atlas tools are available in the session. Verify with the whoami tool, which echoes your identity and workspace.

4. Connect Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project only). Cursor resolves ${env:ATLAS_API_KEY} from its environment, so the key itself is not persisted in the JSON:

{
  "mcpServers": {
    "atlas": {
      "url": "https://mcp.dev.atlas.design/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ATLAS_API_KEY}"
      }
    }
  }
}

Reload Cursor, then enable the atlas server under Settings → MCP. Cursor must inherit the environment variable — for example, launch it from the shell where you loaded the key.

5. Connect Codex

Add the server to ~/.codex/config.toml (all projects) or .codex/config.toml (this project only). Codex's bearer_token_env_var setting reads the key loaded in step 1 instead of storing it in the config file:

# ~/.codex/config.toml
[mcp_servers.atlas]
url = "https://mcp.dev.atlas.design/mcp"
bearer_token_env_var = "ATLAS_API_KEY"

Common pitfalls

• Pasting the key into a saved config file. Typing the raw key into Claude's MCP configuration, .cursor/mcp.json, or .codex/config.toml persists it to disk. Use the environment-variable reference syntax shown above (${ATLAS_API_KEY} / ${env:ATLAS_API_KEY} / bearer_token_env_var) instead.

• Typing the key directly into a shell command. This leaves it recoverable in shell history. Use the hidden read -rsp prompt so the key is never echoed or logged.

• Launching the client from a different shell than the one that loaded the key. Since the key is exported as an environment variable, the client process needs to inherit it — a new shell or a GUI-launched app may not have ATLAS_API_KEY set.

• Assuming one key works across workspaces. A key authenticates exactly one workspace. Connecting a second workspace requires creating and loading a separate key for it.

Frequently asked questions

Can the platform agent run nodes, not just build the graph?

Not in this version. The agent's turns are stateless — it can construct or edit a graph, but running nodes is outside its current scope.

How do I tell which projects were created through MCP?

They're labeled "via MCP." The list_projects and get_project tools return a createdViaMcp field, and the Projects page can be filtered by MCP origin for workspaces with MCP access.

Does an MCP tool have more access than the person who created the key?

No. Every MCP tool runs with the same permissions as the key's owner and enforces the same permission matrix as the web app.

Can I use the same key for more than one workspace?

No — one key authenticates one workspace. Use a separate key for each workspace you want to connect.