> ## Documentation Index
> Fetch the complete documentation index at: https://attlas.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace MCP

> Create Workspace API keys to connect AI coding assistants and desktop tools to your Attlas workspace over 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.

<Tip>
  After connecting the MCP, we recommend installing the [Attlas skills](/docs/mcp/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.
</Tip>

***

## Quickstart

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

<Steps>
  <Step title="Create an API key">
    1. In the Attlas dashboard, open **Workspace settings**.
    2. Go to the **API keys** (or **MCP**) tab.
    3. Click **Create API key**.
    4. Enter a name (e.g. `Cursor assistant` or `Claude Code`).
    5. Choose your permissions (**Write** to create and edit resources, or **Delete** if you require deletion privileges).
    6. Click **Create key** and copy your secret key (`atk_...`) immediately.

    <Warning>
      Your API key is only displayed once. Store it securely. Attlas cannot display the secret again once the dialog is closed.
    </Warning>
  </Step>

  <Step title="Configure your AI client">
    The workspace MCP endpoint is hosted at:

    ```text theme={null}
    https://mcp.attlas.so
    ```

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

    <CodeGroup>
      ```bash Claude Code theme={null}
      # 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"
      ```

      ```json Cursor theme={null}
      {
        "mcpServers": {
          "attlas": {
            "url": "https://mcp.attlas.so",
            "headers": {
              "Authorization": "Bearer atk_your_api_key"
            }
          }
        }
      }
      ```

      ```json Claude Desktop theme={null}
      {
        "mcpServers": {
          "attlas": {
            "command": "npx",
            "args": [
              "mcp-remote",
              "https://mcp.attlas.so",
              "--header",
              "Authorization: Bearer atk_your_api_key"
            ]
          }
        }
      }
      ```

      ```json VS Code theme={null}
      {
        "servers": {
          "attlas": {
            "type": "http",
            "url": "https://mcp.attlas.so",
            "headers": {
              "Authorization": "Bearer atk_your_api_key"
            }
          }
        }
      }
      ```

      ```toml Codex theme={null}
      [mcp_servers.attlas]
      command = "npx"
      args = [
        "mcp-remote",
        "https://mcp.attlas.so",
        "--header",
        "Authorization: Bearer atk_your_api_key"
      ]
      ```
    </CodeGroup>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Verify the connection">
    Test your setup by asking your assistant:

    ```text theme={null}
    List my Attlas chats
    ```

    Your assistant will call the `list_chats` tool and return the list of chats with their numeric identifiers.
  </Step>
</Steps>

***

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

<Steps>
  <Step title="Open the custom connector dialog">
    In Claude, go to **Settings → Connectors → Add custom connector** (Team and Enterprise: **Organization settings → Connectors → Add → Custom**).
  </Step>

  <Step title="Enter the URL">
    ```text theme={null}
    https://mcp.attlas.so
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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                                                                                             |

    <Warning>
      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`.
    </Warning>
  </Step>

  <Step title="Add the connector">
    Click **Add**, then enable Attlas from the **+** menu in a conversation.
  </Step>
</Steps>

<Note>
  **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](#quickstart) above).
</Note>

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

<Warning>
  Only grant the **Delete** permission to trusted workflows where automated cleanup or resource deletion is explicitly required.
</Warning>

***

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