Workspace MCP

Workspace API keys let external developer tools and AI assistants (Claude Code, Cursor, Claude Desktop, VS Code, and Codex) connect to your entire Attlas workspace using the Model Context Protocol (MCP). Attlas exposes 67 tools in total across your workspace: 30 read tools, 30 write tools, and 7 delete tools. Unlike the public chat MCP endpoint, workspace API keys are private, scoped credentials that cover all chats, knowledge documents, triggers, contacts, forms, campaigns, and analytics in your workspace.

Your assistant already knows how to set up and improve an Attlas chat. Ask “help me set up my chat” or “what should I add to my sales chat” and it guides you step by step. Nothing to install.

You can do the same from the dashboard with the Agent

Quickstart

Connect your AI assistant to your Attlas workspace in three steps:

Create an API key

In the Attlas dashboard, open Workspace settings.
Go to the API keys (or MCP) tab.
Click Create API key.
Enter a name (e.g. Cursor assistant or Claude Code).
Choose your permissions (Write to create and edit resources, or Delete if you require deletion privileges).
Click Create key and copy your secret key (atk_...) immediately.

Your API key is only displayed once. Store it securely. Attlas cannot display the secret again once the dialog is closed.

Configure your AI client

The workspace MCP endpoint is hosted at:

https://mcp.attlas.so

Select your AI tool below to copy the setup command or configuration file:

claude mcp add attlas --transport http https://mcp.attlas.so \
  --header "Authorization: Bearer atk_your_api_key"

{
  "mcpServers": {
    "attlas": {
      "url": "https://mcp.attlas.so",
      "headers": {
        "Authorization": "Bearer atk_your_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "attlas": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.attlas.so",
        "--header",
        "Authorization: Bearer atk_your_api_key"
      ]
    }
  }
}

{
  "servers": {
    "attlas": {
      "type": "http",
      "url": "https://mcp.attlas.so",
      "headers": {
        "Authorization": "Bearer atk_your_api_key"
      }
    }
  }
}

[mcp_servers.attlas]
command = "npx"
args = [
  "mcp-remote",
  "https://mcp.attlas.so",
  "--header",
  "Authorization: Bearer atk_your_api_key"
]

If you use Cursor, click the Add to Cursor button directly inside the Attlas API keys tab to configure the connection with a single click.

Verify the connection

Test your setup by asking your assistant:

List my Attlas chats

Your assistant will call the list_chats tool and return the list of chats with their numeric identifiers.

Claude web and desktop (custom connector)

To connect from claude.ai or the Claude desktop app, add Attlas as a custom connector. The workspace endpoint authenticates with an API key, not OAuth, so a few fields need specific values.

Open the custom connector dialog

In Claude, go to Settings → Connectors → Add custom connector (Team and Enterprise: Organization settings → Connectors → Add → Custom).

Enter the URL

https://mcp.attlas.so

Set Authentication to None

After you continue, Claude probes the URL and may pre-select Always required, marked Detected. This is a false positive: the server returns 401 to the unauthenticated probe, and Claude reads that as OAuth.Select None instead. The description on that option says it explicitly: “or for servers that use an API key rather than OAuth.” The OAuth client section then disappears.

Add the key as a request header

Open Request headers and add one header:

Field	Value
Name	`authorization` (pick it from the list; lower-case is fine, HTTP header names are case-insensitive)
Value	`Bearer atk_your_api_key`
Required	checked

Enter the value exactly as the server expects it, including the word Bearer and one space before the key. Claude sends the value verbatim and adds no scheme. atk_... on its own is sent as Authorization: atk_... and the server rejects it with 401.

Add the connector

Click Add, then enable Attlas from the + menu in a conversation.

Request headers is a beta feature available to a limited set of organizations. If you don’t see that section, connect with Claude Code or mcp-remote instead (see Quickstart above).

Troubleshooting

Symptom	Cause	Fix
Connection fails, Claude asks to sign in with OAuth	Authentication left on Always required, or the header value is missing the `Bearer` prefix	Remove the connector, re-add with None and a correct `Bearer atk_...` value
`401` on every call	Wrong, revoked, or malformed key; value sent without `Bearer`	Check the key in the Attlas API keys tab; re-add the connector with the exact value
Tools missing after connecting	The key’s scope doesn’t include them	Create a key with Write or Delete scope
Works in Claude Code but not on claude.ai	Request-headers beta not enabled for your org	Use Claude Code or `mcp-remote`, or contact Claude support to request access
`429 Rate limit exceeded`	More than 120 calls in one minute with the same key	Wait the number of seconds given in the `retry-after` header, then retry

Permission scopes

When creating an API key, select the permissions that match your use case:

Scope	UI label	What it can do
`read`	Read	View and search chats, documents, triggers, contacts, conversations, and analytics. Included by default on all keys.
`write`	Write	Create and update documents, corrections, triggers, contacts, branding, avatar, SEO, and chat settings. Automatically includes Read permissions.
`destructive`	Delete	Delete chats, documents, triggers, contacts, conversations, forms, and campaigns. Chats and documents go for good. Triggers, contacts, forms, and campaigns stay 30 days in the trash, so you can restore them. Automatically includes Write and Read permissions.

Only grant the Delete permission to trusted workflows where automated cleanup or resource deletion is explicitly required.

Plan requirements

The workspace MCP server itself works on every plan. A few actions follow the same plan limits as the dashboard:

Action	Requirement
Creating a chat (`create_chat`)	Uses one chat from your plan’s quota. Returns `quota_exceeded` when none is left.
Reading metrics, trends, rankings, or generating a report	The range only goes back as far as your plan’s history window (Free: 90 days, Starter: 1 year, PRO: 2 years). Wider ranges are trimmed to that window.
Adding a YouTube, Instagram, TikTok, Facebook, or X video link, or an audio file, to a knowledge base	Starter or PRO. Web page links work on every plan.
Adding a file upload step to a form (`create_form`, `update_form`)	Pro plan and above.
Removing the Attlas branding badge (`update_branding`)	Brand add-on.
Customizing chat SEO metadata (`update_seo`)	Starter or PRO.
Editing a chat’s connected SQL database settings	Starter or PRO.
Bubble or popup embed code (`get_embed_code`)	Pro plan. Standard iframe embed works on every plan.

Your assistant can call can_use to check an action against your plan, and get_usage to see your remaining chats, messages, and characters.

Available tools

Attlas provides 67 tools in total across read, write, and delete scopes. Each tool needs the scope shown next to it, and a key only sees the tools its scope allows.

Chats and setup

Tool	Scope	What it does
`list_chats`	Read	Lists your chats with their ids. Your assistant calls it first.
`get_chat_overview`	Read	Everything about one chat in one read, plus a ranked list of what is missing.
`get_chat_config`	Read	A chat’s settings: objective, lead capture, integrations, avatar, SEO, business info.
`preview_chat`	Read	Shows a live preview of the public chat. Messages sent in the preview are free and do not count in analytics.
`get_embed_code`	Read	Generates ready-to-paste embed snippets (standard iframe, bubble button, or popup trigger) with optional channel tracking.
`read_skill`	Read	Accesses Attlas product playbooks and best practices (guided setup, triggers, theme, industries, knowledge).
`read_url_preview`	Read	Fetches public metadata and e-commerce product prices from a URL before creating a trigger.
`read_instagram_profile`	Read	Extracts profile details, avatar picture URL, and external links from an Instagram handle.
`read_linkedin`	Read	Extracts profile or company details, logo, summary, and links from LinkedIn.
`list_theme_presets` / `list_archetypes`	Read	The themes and personalities you can pick from.
`create_chat`	Write	Creates a new chat.
`create_channel`	Write	Adds a named distribution channel or ad campaign with an optional welcome headline.
`update_chat`	Write	Name, description, welcome message, and which tab opens first.
`update_activity_profile`	Write	Business info: website, email, phone, address, opening hours, company or person.
`set_objective`	Write	Support, appointment booking, or lead capture (with optional form_id), plus your own instructions.
`set_personality`	Write	Tone of voice, or a ready-made personality.
`update_theme`	Write	Colors and visual theme.
`update_avatar`	Write	Avatar from an image URL or an emoji.
`update_social_links`	Write	The row of social icons at the bottom of the chat.
`update_seo`	Write	Meta title, meta description, and share image.
`update_branding`	Write	Shows or hides the “Powered by Attlas” badge.
`update_database_connection`	Write	Name, description, currency, and on/off of a connected SQL database. Credentials stay untouched.

Knowledge

Tool	Scope	What it does
`list_documents` / `read_document`	Read	Lists a chat’s documents with their status, or reads one in full.
`create_document`	Write	Adds a text document.
`ingest_url`	Write	Adds a web page, a file link, or a video (YouTube, TikTok, Instagram, X).
`update_document`	Write	Edits a text document. Only the difference in length counts against your quota.
`clean_document`	Write	Reformats a messy imported document.
`create_correction`	Write	Teaches the chat the right answer to a question it got wrong.

Adding or editing knowledge takes a moment. These tools answer right away with a processing status, and your assistant checks list_documents until the document is ready.

Triggers

Tool	Scope	What it does
`list_triggers`	Read	Lists a chat’s triggers, including form triggers and campaign welcome triggers.
`create_trigger` / `update_trigger`	Write	Adds or edits a trigger, including form triggers (with form_id) and campaign triggers (with campaign_id).
`reorder_triggers`	Write	Changes the order and nesting.
`generate_questions`	Write	Suggests visitor questions from your documents, without creating anything.
`generate_and_nest`	Write	Generates questions and places them under a trigger in one step.

Forms

Tool	Scope	What it does
`list_forms`	Read	Lists a chat’s forms, step count, contact fields, and where each form is plugged. Pass `trashed: true` to list forms in the 30-day trash.
`read_form`	Read	Reads a full form with parsed steps, question options, and thank-you markdown.
`get_form_funnel`	Read	Returns 30-day funnel metrics: drop-offs per step, starts by source, and completed leads.
`create_form`	Write	Creates a multi-step question form with structured steps, optional file upload (Pro), a thank-you note, and an optional redirect URL.
`update_form`	Write	Updates a form’s name, steps, thank-you message, or redirect URL while preserving step IDs for funnel tracking.
`restore_form`	Write	Restores a deleted form from the 30-day trash.

Campaigns

Tool	Scope	What it does
`list_campaigns`	Read	Lists ad campaigns with their unique link, welcome headline, triggers, and 30-day performance. Pass `trashed: true` to view trashed campaigns.
`update_campaign`	Write	Updates a campaign’s welcome headline, launch trigger on arrival, or renames the campaign.
`copy_trigger_to_campaign`	Write	Copies an existing menu trigger and its nested sub-tree into a campaign’s welcome screen.
`restore_campaign`	Write	Restores a deleted campaign and its welcome triggers from the 30-day trash.

Contacts and appointments

Tool	Scope	What it does
`list_contacts`	Read	Lists contacts captured by your chats, with their stage.
`list_appointments`	Read	Lists booked appointments.
`update_contact`	Write	Changes a contact’s stage or internal notes.

Insights

Tool	Scope	What it does
`get_metrics`	Read	Messages, views, clicks, leads, conversion, and knowledge coverage, compared to the previous period.
`get_timeseries` / `get_rankings`	Read	Activity over time, and top triggers, countries, devices, and channels.
`list_signals`	Read	Questions your chat could not answer, downvoted answers, and visitors who left.
`list_conversations` / `read_conversation`	Read	Visitor conversations and their messages.
`list_reports` / `read_report`	Read	Reports already generated.
`generate_report`	Write	Writes an analytics report for a period.

Plan

Tool	Scope	What it does
`get_usage`	Read	Your plan and remaining chats, messages, and characters.
`can_use`	Read	Checks whether your plan allows an action.

Delete

Tool	Scope	What it does
`delete_chat`	Delete	Deletes a chat and everything in it. Permanent.
`delete_document`	Delete	Deletes a document and gives back its characters. Permanent.
`delete_trigger` / `delete_contact`	Delete	Moves a trigger or contact to the trash for 30 days.
`delete_form`	Delete	Moves a form to the trash for 30 days and unplugs it from lead capture and triggers.
`delete_campaign`	Delete	Moves an ad campaign and its welcome triggers to the trash for 30 days.
`delete_conversation`	Delete	Hides a conversation everywhere. You cannot restore it through MCP.

What stays in the dashboard

Some settings need you at attlas.so. Your assistant tells you when a request falls here:

Changing a chat’s URL.
Connecting an integration: Google Calendar, Notion, a SQL database, Bandsintown, the Meta Conversions API, a custom domain, or a webhook. Once connected, your assistant can configure and use it.
Access mode, password, and public or private visibility.
Plan, billing, and add-ons.
Workspace members and invitations.

Monitoring activity and audit logs

The Recent activity table at the bottom of the API keys tab logs every MCP call made to your workspace:

When: Relative timestamp of the request.
Key: Prefix of the key used (atk_...).
Tool: The MCP tool called (e.g. list_chats, create_document, delete_trigger).
Target: The resource touched by the operation.
Result: Success (ok) or error badge.

Turn on Changes only to hide read calls.

Restore deleted items

If a tool deleted a trigger, contact, form, or campaign by mistake, click Restore in its activity row within 30 days.

Home

Learn

MCP

Quickstart

Claude web and desktop (custom connector)

Troubleshooting

Permission scopes

Plan requirements

Available tools

Chats and setup

Knowledge

Triggers

Forms

Campaigns

Contacts and appointments

Insights

Plan

Delete

What stays in the dashboard

Monitoring activity and audit logs

Restore deleted items

​Quickstart

​Claude web and desktop (custom connector)

​Troubleshooting

​Permission scopes

​Plan requirements

​Available tools

​Chats and setup

​Knowledge

​Triggers

​Forms

​Campaigns

​Contacts and appointments

​Insights

​Plan

​Delete

​What stays in the dashboard

​Monitoring activity and audit logs

​Restore deleted items

Quickstart

Claude web and desktop (custom connector)

Troubleshooting

Permission scopes

Plan requirements

Available tools

Chats and setup

Knowledge

Triggers

Forms

Campaigns

Contacts and appointments

Insights

Plan

Delete

What stays in the dashboard

Monitoring activity and audit logs

Restore deleted items