MCP setup

Connect supported AI agents through OAuth 2.1 to call Atomic tools with your existing workspace and project permissions. Create a personal access token only for a client that cannot connect with OAuth. MCP is available for projects on Starter and higher plans. A token remains personal, but Atomic checks the plan of the project selected for each MCP request.

Questions this page should answer

How do I connect my AI agent with OAuth?
Which MCP endpoint should my client use?
When do I need a personal access token?
How do I confirm tools are available in my client?

Before you connect

In Atomic, open Profile settings and select MCP.
Use the MCP endpoint:

https://app.atomicagi.com/api/mcp

Copy the MCP server URL from the page and paste it into your AI agent’s custom connector setup. Clients with OAuth support open Atomic sign-in and ask you to approve access. No personal access token is required.

What this page gives you

Your Atomic MCP endpoint.
A copyable server URL used by OAuth-enabled custom connectors.
Personal access token creation and revocation for clients without OAuth.
The configuration pattern for other remote HTTP MCP clients.

Important: If you need a personal access token, treat it like a password. Store it in your client config or secret manager, not in shared docs or chat threads.

How project access works

OAuth connections and personal access tokens inherit your user permissions. They cannot access projects you cannot already open in Atomic, and they cannot use tools for projects below the Starter plan. You do not need to put a project id in your client configuration. When a tool runs:

Atomic uses the only accessible project automatically when your account has access to one project.
If your account has access to multiple projects, Atomic returns a project chooser with each project id, name, domain, and workspace.
Ask the AI client to use the right project and rerun the tool with projectId in the tool arguments.

Cursor

Cursor can connect directly to Atomic’s HTTP MCP endpoint. Open Cursor MCP settings and add this server to your mcp.json:

{
  "mcpServers": {
    "atomic-ai": {
      "url": "https://app.atomicagi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer atmcp_YOUR_TOKEN"
      }
    }
  }
}

After saving, refresh the atomic-ai MCP server in Cursor. The tools list should load without any project-specific header.

Claude custom connector

Claude and Claude Desktop can connect directly to Atomic using the remote custom connector flow. You do not need to paste an MCP token or configure OAuth client credentials.

In Claude, open Settings > Connectors.
Select Add custom connector.
Enter Atomic AI as the name.
Enter the remote MCP server URL:

https://app.atomicagi.com/api/mcp

Leave the optional OAuth Client ID and OAuth Client Secret empty.
Select Add, then Connect.
Sign in to Atomic and approve the requested tool access.

Claude uses short-lived OAuth access tokens and refreshes them automatically. Disconnect the connector in Claude to revoke its OAuth grant.

ChatGPT custom app

ChatGPT can connect to Atomic through an OAuth-enabled custom MCP app. You do not need to create or paste a personal MCP token.

Enable developer mode in ChatGPT.
Open Settings > Apps and create a custom app.
Enter the Atomic MCP endpoint:

https://app.atomicagi.com/api/mcp

Choose OAuth authentication and let ChatGPT register its public client automatically.
Sign in to Atomic and approve the requested tool access.

Atomic accepts ChatGPT’s current per-app callback URL and its documented legacy callback. The OAuth client remains restricted to the exact callback URI ChatGPT registered.

Codex

Codex can add Atomic as a remote MCP server and authenticate through OAuth:

codex mcp add atomic-ai --url https://app.atomicagi.com/api/mcp
codex mcp login atomic-ai

Open the authorization URL if prompted, sign in to Atomic, and approve access. Restart Codex after login so the Atomic tools are available in a new session.

Claude Desktop local configuration

For clients that use Claude Desktop’s local claude_desktop_config.json rather than remote custom connectors, use mcp-remote to bridge to Atomic’s HTTP MCP endpoint. Add this server to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "atomic-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://app.atomicagi.com/api/mcp",
        "--header",
        "Authorization:${ATOMIC_MCP_AUTH_HEADER}"
      ],
      "env": {
        "ATOMIC_MCP_AUTH_HEADER": "Bearer atmcp_YOUR_TOKEN"
      }
    }
  }
}

Fully quit and reopen Claude Desktop after editing the file.

Claude Code

Claude Code can add Atomic as a remote HTTP MCP server from the terminal:

claude mcp add --transport http atomic-ai https://app.atomicagi.com/api/mcp \
  --header "Authorization: Bearer atmcp_YOUR_TOKEN"

Then run this inside Claude Code:

/mcp

Confirm that atomic-ai is connected and that tools are available.

Other MCP clients

Native and desktop MCP clients can use Atomic OAuth when they support dynamic client registration, authorization code flow with PKCE, and an HTTP loopback callback on localhost, 127.0.0.1, or ::1. Atomic validates and stores the exact registered callback URI. Clients without OAuth support can use a personal bearer token: Use Atomic as a remote HTTP MCP server when the client supports HTTP MCP:

{
  "url": "https://app.atomicagi.com/api/mcp",
  "headers": {
    "Authorization": "Bearer atmcp_YOUR_TOKEN"
  }
}

If the client only supports local stdio servers, use mcp-remote with the Claude Desktop pattern.

Test the connection

You can test the token and endpoint with curl:

curl -X POST https://app.atomicagi.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer atmcp_YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A healthy response includes a tools array.

Quick setup checklist

Choose your AI agent on the Atomic MCP page.
Add the Atomic endpoint in your client and complete OAuth sign-in.
Restart or refresh the MCP client.
Confirm the Atomic tools list appears.
Run a harmless read-only tool first.
If asked to choose a project, pass the returned projectId on the next call.

Troubleshooting

The client shows no tools

Check that the MCP token is active, the endpoint ends with /api/mcp, and the authorization header starts with Bearer .

Claude Desktop says the config is invalid

Use the command and args format with mcp-remote. Claude Desktop does not accept the direct url and headers format used by Cursor. Confirm that the connector URL is exactly https://app.atomicagi.com/api/mcp and that the optional OAuth Client ID and OAuth Client Secret fields are empty. Remove and add the connector again if Claude cached a failed setup attempt.

The tool asks you to choose a project

Choose the project by name or domain. The AI client should call the tool again with the returned projectId in the tool arguments.

A token was shared by mistake

Revoke it from Profile settings > MCP immediately and create a new token.

Keep in mind

MCP tokens inherit your user permissions.
Claude custom connectors use OAuth and do not require a manually created MCP token.
ChatGPT custom apps and standards-compliant native MCP clients can use OAuth without a personal MCP token.
Tokens do not grant access to projects you cannot open in Atomic.
Project selection is explicit when your account can access multiple projects.
Revoke old tokens when you stop using a client.

Get started

Data

Automation

Settings

Questions this page should answer

Before you connect

What this page gives you

How project access works

Cursor

Claude custom connector

ChatGPT custom app

Codex

Claude Desktop local configuration

Claude Code

Other MCP clients

Test the connection

Quick setup checklist

Troubleshooting

The client shows no tools

Claude Desktop says the config is invalid

The tool asks you to choose a project

A token was shared by mistake

Keep in mind

Where to go next

​Questions this page should answer

​Before you connect

​What this page gives you

​How project access works

​Cursor

​Claude custom connector

​ChatGPT custom app

​Codex

​Claude Desktop local configuration

​Claude Code

​Other MCP clients

​Test the connection

​Quick setup checklist

​Troubleshooting

​The client shows no tools

​Claude Desktop says the config is invalid

​Claude custom connector does not open Atomic sign-in

​The tool asks you to choose a project

​A token was shared by mistake

​Keep in mind

​Where to go next

Questions this page should answer

Before you connect

What this page gives you

How project access works

Cursor

Claude custom connector

ChatGPT custom app

Codex

Claude Desktop local configuration

Claude Code

Other MCP clients

Test the connection

Quick setup checklist

Troubleshooting

The client shows no tools

Claude Desktop says the config is invalid

Claude custom connector does not open Atomic sign-in

The tool asks you to choose a project

A token was shared by mistake

Keep in mind

Where to go next