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_projectsandget_projecttools expose acreatedViaMcpfield, 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:
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:
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:
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:
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.tomlpersists 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 -rspprompt 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_KEYset.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.
Last updated