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.

Organize items in folders

MCP tools can organize Content documents, Workflows, Grids, and saved custom Reports using the same folders as the app. Each tool uses the selected project and the collection’s existing permissions and plan requirements. Reading folders requires view permission; creating, editing, and moving require full permission for that collection.

Collection	List folders	Create folder	Edit folder	Move item
Content	`list_content_folders`	`create_content_folder`	`update_content_folder`	`move_content_to_folder`
Workflows	`list_workflow_folders`	`create_workflow_folder`	`update_workflow_folder`	`move_workflow_to_folder`
Grids	`list_grid_folders`	`create_grid_folder`	`update_grid_folder`	`move_grid_to_folder`
Reports	`list_report_folders`	`create_report_folder`	`update_report_folder`	`move_report_to_folder`

List folders first to get folder IDs, names, descriptions, and item-to-folder assignments. Use the existing Content, Workflow, Grid, or Report listing tools to discover item IDs and details. Items absent from the assignments are at the top level. To create a folder, supply name and an optional description. To edit one, supply folderId, name, and description. Both text fields replace their saved values; use an empty description to clear it. Folder names support up to 120 characters and descriptions up to 2,000 characters. To move an item, supply its itemId and destination folderId. Use a string ID for Content and a numeric ID for Workflows, Grids, and Reports. Set folderId to null to move the item back to the top level. The item and folder must belong to the same project and collection. Only saved custom reports can be moved; built-in reports remain at the top level. For example, after identifying report 42 and a report folder 7, call move_report_to_folder with:

{ "itemId": 42, "folderId": 7 }

Move that report out again with:

{ "itemId": 42, "folderId": null }

A connected client can revise, approve, or request changes to an existing Grid Social post. This uses the same review history and permissions as the Social posts screen.

Read get_grid_sheet and identify the post’s sheetId, rowId, columnId, and current revision.
Call review_grid_social_post with those IDs, expectedRevision, and an action: revise, approve, or request_changes.
For revise, send the complete editable content, including platform, postType, authorName, and body. Preserve the fields you want to keep and omit obsolete media fields when changing formats. Do not send server-owned status, history, actor, or revision fields. Keep carousel imageUrls and imageAltTexts in the same order.
Review the returned revision. A revision returns the post to awaiting approval. Approve separately using the new revision; do not reuse the old one.
For request_changes, include actionable feedback. If another editor changed the revision, read the sheet again and review the newer content before retrying.

For example, after reading the current post and confirming revision 3 is ready, an approval call uses:

{
  "sheetId": 12,
  "rowId": 34,
  "columnId": 56,
  "expectedRevision": 3,
  "action": "approve"
}

These IDs are illustrative; use IDs and the revision returned by your own sheet. Never use update_grid_cell or update_grid_cells to revise an existing Social post. Reading requires access to the project’s workflows. Revising requires Workflows write access; approving or requesting changes requires Social post approval write access. See reviewer permissions. Review actions do not publish or schedule a post. Use the approved revision in a separate publishing workflow, then inspect the provider result. This connector procedure has no separate product screen; its resulting revision and approval state appear in the existing Social post review dialog.

Test an AI-search prompt

Ask your connected agent to test prompt text on any engine available on the project’s plan. The test_ai_search_prompt_run tool takes prompt and engine, with an optional promptCategory, then returns a runId. Tests do not add saved prompts, create groups, select engines, or enable ongoing tracking. Saving prompts for regular tracking is a separate action. The agent can use get_ai_search_prompt_run to check progress and read the answer, citations, and brand classifications. Tests share a billing-cycle run allowance with regular prompt tracking. Each prompt tested on one engine uses one run. The allowance per billing cycle follows your plan’s tracking schedule: Starter has 825 runs (75 × 11 scheduled executions every three days), Team has 3,840 (240 × 16 scheduled executions every two days), Team Max has 13,020, Frontier Analyst has 24,800, and Frontier Growth has 49,600. The daily plans use capacity × 31. Tests use this same allowance, with no separate test pool. A successful billing renewal resets the used-run count. Duplicate payment events and plan changes do not reset it. Failed attempts use a run; requesting a prompt and engine that already has a pending run returns that run without using another. Test runs require full AI-search permission.

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

If your client supports dynamic registration, connect it to https://app.atomicagi.com/api/mcp and use the authorization code flow with S256 PKCE. Register the callback URI your client uses to finish sign-in.

Where the client runs	Callback to register
Hosted web app	An exact HTTPS URI on a public domain, such as `https://client.example.com/oauth/callback`. Use a domain name without wildcards.
Desktop app	An HTTP loopback URI with an explicit port, such as `http://127.0.0.1:8765/callback`. Atomic also accepts `localhost` and `[::1]`. Leave the query string empty.
Hosted app with a desktop extension	Register both callback URIs together and omit `application_type` from the registration request.

You can register up to five distinct callback URIs. Use one exactly as registered when starting sign-in, including the port and path. Callback URIs must be free of embedded credentials and fragments. 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.

Where to go next

Add tracked prompts through MCP

Use add_project_prompts to add AI-search prompts directly to the selected Atomic project. Use update_project_prompt with a promptId from get_project_prompts to change text (prompt), funnel stage (promptCategory), topic assignments (promptTopicIds) or tracking status (isActive). Supply at least one changed field; omitted fields are preserved and an empty topic array clears assignments. Updates do not schedule an immediate tracking run. Use delete_project_prompt with promptId to permanently remove a tracked prompt. Both tools require full AI Search permission and restrict changes to the selected project. To pause tracking, use update_project_prompt with isActive: false. Supply a non-empty prompts list. Each item needs prompt text and a promptCategory: awareness, consideration, decision, or branded. You can also supply promptTopicIds for topics in that project.

{
  "prompts": [
    {
      "prompt": "What are the best CRM tools for small agencies?",
      "promptCategory": "consideration"
    }
  ]
}

The tool uses the engines selected in the project’s prompt tracking settings and checks its available prompt capacity. Saving schedules tracking runs, which may use AI credits. It does not select engines for you. Use get_project_prompts first to check existing prompts: exact-text duplicates update their stage without scheduling another tracking run. The response reports savedPrompts, totalPrompts submitted after deduplication, and remainingPrompts capacity (-1 means unlimited).

Project setup tools

Start with list_workspaces and list_projects, then inspect get_project or get_project_setup_status using an explicit projectId. Tool discovery and both inspection tools work before MCP entitlement is enabled, but require accepted project access and general-settings read permission. Source and tracking details are marked restricted when the connected user lacks the corresponding permission.

Tool	Inputs	Purpose
`get_project`	`projectId`	Saved settings, plan and entitlements, credit counters, source IDs and prompt capacity
`get_project_setup_status`	`projectId`	Required blockers and optional setup steps, marked configured, missing or restricted
`update_project`	Optional `name`, `domain`, `industry`, `serpLocationId`, `brandMentionVariations`; at least one field	Update project-level settings; preserve omitted fields
`get_serp_locations`	Optional `search`	Find supported IDs by location name, country code or language code
`get_project_prompt_topics`	Project context	List prompt topics and IDs
`create_project_prompt_topic`	`name`, optional `description`	Create a prompt topic
`update_project_prompt_topic`	`topicId`, optional `name`, `description`; at least one changed field	Rename a topic or change its description; empty description clears it
`delete_project_prompt_topic`	`topicId`	Delete a topic without deleting its prompts
`delete_project_competitor`	`competitorId`	Remove a tracked competitor belonging to this project
`create_workspace_subscription_checkout`	`workspaceId`, `projectId`, `paymentPlanId`, optional `initialSeatQuantity`	Return a Stripe checkout link for the first workspace subscription

Setup status reports saved configuration, not live integration health or indexing completion. Knowledge, publishing, competitors, brand kits and tracking are optional steps according to your goals. A knowledge base can be configured before any files are indexed. Credit status uses the same contract as Atomic: available: -1 means unlimited credits. Checkout requires an existing project and full workspace billing permission. create_project creates the requested project before billing. Without a subscription it returns checkout for that new project; never substitute another project. Complete payment interactively at the returned checkout link; the link alone does not activate a plan. Use Atomic workspace billing interactively when a workspace subscription already exists. Autonomous MCP tools cannot change an existing subscription. New Google connections also require interactive sign-in in Atomic. Project updates require full general-settings permission. Topic mutations require full AI Search permission; competitor deletion requires full Competitors permission. Updating a project SERP location does not overwrite existing brand-kit targeting. Use update_brand_kit separately when its search targeting should also change.

Project onboarding and AI Search reporting tools

create_project requires a selected paymentPlanId, but does not require an existing subscription. It creates the requested project first. Without a subscription (or after a canceled subscription), it returns billing.status: checkout_required and a checkout URL for that same project. paymentPlanId remains null until payment succeeds; requestedPaymentPlanId identifies the selected plan. With an active subscription, it leaves the new project unbilled and returns billing.status: interactive_billing_required with nextAction: open_workspace_billing. Select and confirm the plan for this project in Atomic workspace billing. MCP does not activate a plan, invoice prorations, or end a trial. If billing preparation fails after creation, the tool returns the created project ID, billing.status: failed, and recovery tool arguments. Inspect the actual project plan before retrying billing; do not repeat project creation or upgrade an unrelated project. Checkout links require interactive payment and do not activate plans by themselves. Use list_workspaces to choose a workspace, get_payment_plans to choose a payment plan, and list_projects to find the stable project ID. Project tools accept projectId when your client needs to select a project.

Tool	Inputs	Returns
`list_workspaces`	None	Accepted workspaces for the connected user, including empty workspaces
`get_payment_plans`	None	Active canonical project plans with IDs, prices and billing intervals
`create_project`	`workspaceId`, `name`, `domain`, `industry`, `serpLocationId`, `paymentPlanId`; optional slug and brand variations	Project ID, plan and billing details; requires project creation and billing permissions
`get_gsc_url_indexing_status`	`url`	Live indexing status, coverage, last crawl and canonical URLs; requires connected GSC
`list_ai_search_prompt_runs`	Optional prompt ID, dates, engines, brand-mentioned filter, page and limit	Every run status, country, top five ranked brands (name, domain, position, mention frequency), timestamps, IDs, pagination and next scheduled run time
`get_ai_search_prompt_run`	`runId`	Full answer, brand/competitor classifications and citations
`get_ai_search_selected_engines`	Project context	Selected and available engines, plan limits and prompt capacity
`set_ai_search_selected_engines`	`engines`	Saved selection and updated capacity; plan limits apply
`get_ai_search_project_stats`	Optional dates, engines, category, active status and topic ID	Project visibility, position, sentiment and numeric mention statistics
`get_ai_search_prompt_stats`	`promptId`, optional reporting filters	The same statistics for one prompt
`get_ai_search_stats_timeseries`	Optional prompt ID and reporting filters; `granularity: "week"`	Weekly statistics in one call, with UTC Monday-based weeks
`export_report_pdf`	`reportId`	Downloadable PDF URL, filename and size; requires an existing published report

Statistics default to the last 30 days. Run history includes all dates unless dates are supplied. Weekly boundary buckets are clipped to your requested date range. Mention statistics return mentionCount, validAnswerCount, mentionPercentage and a derived mentionFrequency label. Failed, pending and unclassified answers are excluded. Visibility remains a separate position-weighted metric. An empty sample returns zero counts and percentage, with a null label. get_gsc_keywords and get_gsc_pages support results beyond the first 100 rows. Use page, limit and nextPage to retrieve more results. Zero-click rows are retained. get_citations accepts startDate and endDate. get_sentiment returns structured sentiment data and counts/percentages by default. Set includeRawText: true only when you need the full evaluation text. Adding an existing exact-text prompt updates its stage without starting another run. New prompts still schedule tracking runs.

Reuse a workspace Google connection

These tools reuse a Google account already authorized in Atomic. They do not start OAuth or accept external Google tokens.

Tool	Inputs	Returns
`list_workspace_google_connections`	`workspaceId`	Connection IDs, account names and emails; no OAuth credentials
`list_google_connection_properties`	`workspaceId`, `connectionId`	Imported GSC sites and GA4 properties, including current selected events
`list_ga4_property_events`	`workspaceId`, `connectionId`, `propertyId`; optional dates	Observed GA4 events for the period and current Atomic event selection
`set_project_google_sources`	Project context, `workspaceId`, `connectionId`; `siteId` and/or `propertyId`, optional `eventNames`	Saved project sources and selected events

Use the Atomic siteId and propertyId returned by property discovery. googlePropertyId is Google’s identifier and is not the input record ID. Event discovery defaults to the last 30 days; an event absent from that period may still be configured by name. Read tools require workspace integrations access. Saving requires full workspace integrations access and full project data-sources access. All selected sources must belong to the workspace connection, and the project must belong to that workspace. Connecting GSC follows the app flow and updates the project’s domain to match the selected site. GA4 event selection is stored on the property and shared by projects using that property. Omitting eventNames preserves the current selection; passing [] clears it. This configures Atomic reporting events and does not change Google’s key-event settings.

Get started

Workspace

Settings

Questions this page should answer

Before you connect

What this page gives you

How project access works

Organize items in folders

Test an AI-search prompt

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

Add tracked prompts through MCP

Project setup tools

Project onboarding and AI Search reporting tools

Reuse a workspace Google connection

Questions this page should answer

Before you connect

What this page gives you

How project access works

Organize items in folders

Review Social posts

Test an AI-search prompt

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

Add tracked prompts through MCP

Project setup tools

Project onboarding and AI Search reporting tools

Reuse a workspace Google connection