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). Unlike the public chat MCP endpoint, workspace API keys are private, scoped credentials that cover all chats, knowledge documents, triggers, contacts, and analytics in your workspace.

After connecting the MCP, we recommend installing the Attlas skills. They teach your assistant the right way to use these tools, so requests like “put our pricing page in the chat with questions under it” or “set up my new chat” work in one step.

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:

# Run in your terminal from your project directory:
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

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	Permanently delete chats, documents, triggers, contacts, and conversations. 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
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 to a knowledge base	Starter or PRO (video transcription). Web page links work on every plan.
Removing the Attlas branding badge (`update_branding`)	Brand add-on.
Customizing chat SEO metadata (`update_seo`)	Basic plan or higher.
Editing a chat’s connected SQL database settings	Starter or PRO (advanced integrations).

Available capabilities & tools

Once connected, your assistant can manage all areas of your workspace:

Chat setup, branding & live preview

preview_chat: Render an interactive live preview of your public chat inside MCP Apps hosts without consuming message credits or affecting analytics.
update_chat: Modify chat configuration, goals, and behavior settings.
update_avatar: Set the chat avatar from a public image URL (automatically hosted) or an emoji.
update_branding: Show or hide the “Powered by Attlas” badge (requires the Brand add-on).
update_seo: Set meta title, meta description, and social share image (og:image).
update_social_links: Set social media profile links (X, LinkedIn, Instagram, YouTube, TikTok, etc.) shown on the chat.
update_theme & list_theme_presets: Browse and apply visual color themes.
set_personality & list_archetypes: Customize tone and assign persona archetypes.

Knowledge & continuous learning

create_document: Add text documents directly to the knowledge base.
update_document: Edit text document content with automatic character balance adjustment.
ingest_url: Crawl web pages or transcribe video links (YouTube, TikTok, Instagram, X).
clean_document: Reformat imported documents with AI Markdown cleanup.
create_correction: Teach the chat the definitive answer to questions it previously answered poorly or failed to answer.

Triggers & lead capture

list_triggers, create_trigger, update_trigger, reorder_triggers: Manage buttons, links, and sections on the public chat.
generate_questions: Produce suggested visitor questions based on uploaded documents.
generate_and_nest: Generate questions and nest them under a parent trigger in a single operation.

Insights & signals

list_signals: Review missed questions (weak_answer), downvoted answers (thumbs_down), and visitor drop-offs (left_after).
list_conversations & read_conversation: Inspect visitor conversations and message transcripts.
get_metrics, get_timeseries, get_rankings: Fetch activity stats and conversion rates.
generate_report & read_report: Generate structured summaries of chat performance.

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.

Restore deleted items

If a tool soft-deletes a trigger or contact by mistake, click Restore in the activity row to bring it back to your workspace immediately.

Home

Learn

MCP

Quickstart

Claude web and desktop (custom connector)

Troubleshooting

Permission scopes

Plan requirements

Available capabilities & tools

Chat setup, branding & live preview

Knowledge & continuous learning

Triggers & lead capture

Insights & signals

Monitoring activity and audit logs

Restore deleted items

​Quickstart

​Claude web and desktop (custom connector)

​Troubleshooting

​Permission scopes

​Plan requirements

​Available capabilities & tools

​Chat setup, branding & live preview

​Knowledge & continuous learning

​Triggers & lead capture

​Insights & signals

​Monitoring activity and audit logs

​Restore deleted items

Quickstart

Claude web and desktop (custom connector)

Troubleshooting

Permission scopes

Plan requirements

Available capabilities & tools

Chat setup, branding & live preview

Knowledge & continuous learning

Triggers & lead capture

Insights & signals

Monitoring activity and audit logs

Restore deleted items