> For the complete documentation index, see [llms.txt](https://docs.atlas.design/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.atlas.design/atlas-ai-studio-overview/node-index/mcp.md).

# 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](https://modelcontextprotocol.io/) 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.

<figure><img src="https://3654894688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7boiMixMhR4q36Ns33Y%2Fuploads%2FlsUAK9ldi9KiK0rh31Px%2Fimage.png?alt=media&amp;token=d6bad47e-a6a8-49d4-afa6-7205e951006a" alt="" width="563"><figcaption></figcaption></figure>

### 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.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7boiMixMhR4q36Ns33Y%2Fuploads%2F83AlxwfeoNJNBQLYPNQf%2Fmcp.mp4?alt=media&token=8ae2f278-75ac-4f42-a9d7-b8f9454c4454>" %}

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FR7boiMixMhR4q36Ns33Y%2Fuploads%2FFPROxrqRBIXU5p01EnHT%2F20260813-1116-23.8628858.mp4?alt=media&token=6fc00f31-d47b-485c-93c8-4f47efd0f45c>" %}

### 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:

```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:

```toml
# ~/.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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.atlas.design/atlas-ai-studio-overview/node-index/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.