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

# MCP Server

> Let your AI assistant read and analyse your AeoNut workspace

The AeoNut MCP server connects your AI assistant to your workspace. It works with Claude, Microsoft Copilot, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex and any other MCP client. Once it's connected, your assistant can look through your AI visibility, competitors, content map and content library, and then answer your questions or build reports from that data.

It uses the same [API key](/api/overview#quick-start) as the API, with the default scopes.

<Info>
  Everything the MCP server does is free. It only reads your data and never changes anything in your workspace.
</Info>

## Connect your assistant

The hosted server is at `https://mcp.deepsmith.ai/mcp/ws-uuid`. Every client below connects the same way, with that URL and an `Authorization: Bearer YOUR_API_KEY` header that carries your API key. You don't need to install anything else.

<Info>
  If you have more than one workspace, each one gets its own URL, `https://mcp.deepsmith.ai/mcp/ws-uuid`, which you'll find on **Settings → MCP server** in that workspace. Add one connector per workspace and name each one the way [Connecting multiple workspaces](#connecting-multiple-workspaces) describes.
</Info>

The snippets below use `aeonut-acme` as the connector name, so swap `acme` for your own workspace slug.

<Tabs>
  <Tab title="Claude" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/claude.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=397405da4e0b584de0f64cc24d88b71d" width="24" height="24" data-path="images/mcp-clients/claude.svg">
    Claude on the web, the desktop app and Cowork all share one connector, so you only add it once and it follows your account.

    1. **Settings → Connectors → Add custom connector**
    2. Name it `aeonut-acme` (see [naming](#name-the-connector)), paste `https://mcp.deepsmith.ai/mcp/ws-uuid`, then **Continue**
    3. Authentication: **No sign-in** (this server uses an API key, not OAuth)
    4. **Add header** → name `authorization`, value `Bearer YOUR_API_KEY`
    5. **Add**, then **Connect**. You should see 23 read-only tools.
  </Tab>

  <Tab title="Copilot Studio" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/githubcopilot.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=8dacb0abcf17b433228a5863abe4594f" width="24" height="24" data-path="images/mcp-clients/githubcopilot.svg">
    This works for Microsoft Copilot Studio agents, including ones published to Microsoft 365 Copilot. The person who makes the agent adds the server, and each user gives their own key when they connect.

    1. In the agent: **Tools → Add a tool → New tool → Model Context Protocol**
    2. Server name `aeonut-acme` (see [naming](#name-the-connector)), a short description, Server URL `https://mcp.deepsmith.ai/mcp/ws-uuid`
    3. Authentication **API key** → Type **Header** → name `Authorization`
    4. **Create**, then create a connection with `Bearer YOUR_API_KEY` as the key
  </Tab>

  <Tab title="Claude Code" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/claude.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=397405da4e0b584de0f64cc24d88b71d" width="24" height="24" data-path="images/mcp-clients/claude.svg">
    ```bash theme={null}
    claude mcp add --transport http aeonut-acme https://mcp.deepsmith.ai/mcp/ws-uuid \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/cursor.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=73a3ad2750971d113be96d33f4453464" width="24" height="24" data-path="images/mcp-clients/cursor.svg">
    Go to **Settings → MCP → Add new server**, or edit `~/.cursor/mcp.json`. For a single project, use `.cursor/mcp.json` instead.

    ```json theme={null}
    {
      "mcpServers": {
        "aeonut-acme": {
          "url": "https://mcp.deepsmith.ai/mcp/ws-uuid",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/visualstudiocode.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=1daa5a7a441f8d9773963e58f94d0a05" width="24" height="24" data-path="images/mcp-clients/visualstudiocode.svg">
    Put this in `.vscode/mcp.json`, or run **MCP: Open User Configuration** if you want it in every project. VS Code needs the `servers` key and `"type": "http"`. Don't use the older `.mcp.json` file, because it drops headers without telling you.

    ```json theme={null}
    {
      "servers": {
        "aeonut-acme": {
          "type": "http",
          "url": "https://mcp.deepsmith.ai/mcp/ws-uuid",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/windsurf.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=5ee0368894b875b9149cde7ee72aaad2" width="24" height="24" data-path="images/mcp-clients/windsurf.svg">
    Edit `~/.codeium/windsurf/mcp_config.json`. Windsurf calls the URL field `serverUrl`, so use that name.

    ```json theme={null}
    {
      "mcpServers": {
        "aeonut-acme": {
          "serverUrl": "https://mcp.deepsmith.ai/mcp/ws-uuid",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Gemini CLI" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/googlegemini.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=9afa969d05603df782e175e33155f99d" width="24" height="24" data-path="images/mcp-clients/googlegemini.svg">
    Edit `~/.gemini/settings.json`, or `.gemini/settings.json` for a single project. Gemini calls the URL field `httpUrl`, so use that name.

    ```json theme={null}
    {
      "mcpServers": {
        "aeonut-acme": {
          "httpUrl": "https://mcp.deepsmith.ai/mcp/ws-uuid",
          "headers": { "Authorization": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex" icon="https://mintcdn.com/aeonut/gKCmaBLk3A9FgezM/images/mcp-clients/openai.svg?fit=max&auto=format&n=gKCmaBLk3A9FgezM&q=85&s=0b1b83ea8dd09ee385c4b586c28df90d" width="24" height="24" data-path="images/mcp-clients/openai.svg">
    Edit `~/.codex/config.toml`. Codex reads the key from the environment variable you name and sends it as a bearer token, which means the key never has to sit in the file.

    ```toml theme={null}
    [mcp_servers.aeonut-acme]
    url = "https://mcp.deepsmith.ai/mcp/ws-uuid"
    bearer_token_env_var = "AEONUT_API_KEY"
    ```

    ```bash theme={null}
    export AEONUT_API_KEY=YOUR_API_KEY
    ```
  </Tab>

  <Tab title="Other clients" icon="plug">
    Any client that speaks MCP over HTTP (Streamable HTTP) will work with the URL and the `Authorization` header. These ones are known to work the same way:

    * **Zed**: Settings → MCP servers, remote server with a `headers` block
    * **Raycast**: AI → MCP servers, HTTP headers `Authorization: Bearer YOUR_API_KEY`
    * **JetBrains AI Assistant** (2025.3+): Settings → Tools → AI Assistant → MCP, remote server, expand *HTTP headers*
    * **Perplexity**: Settings → Connectors → Custom connector, API key auth with header `Authorization` (remote connectors are on paid plans and still rolling out)

    If your client only runs local (stdio) servers, you can bridge it to the hosted server with `mcp-remote`. The key goes in an env var because `mcp-remote` splits arguments on spaces and would break the header apart.

    ```json theme={null}
    {
      "mcpServers": {
        "aeonut-acme": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.deepsmith.ai/mcp/ws-uuid", "--header", "Authorization:${AUTH}"],
          "env": { "AUTH": "Bearer YOUR_API_KEY" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  If you don't have a key yet, you can create one under **Settings → API keys** in AeoNut. It's only shown once, so copy it and paste it into the snippet above.
</Tip>

## Connecting multiple workspaces

You add one connector per workspace, and each connector gets its own API key. The key decides which workspace you're in. The workspace id at the end of the URL is only there to keep the URLs distinct.

### Name the connector

Your assistant sees each tool as `mcp__<connector-name>__<tool>`, so the connector name is the only way it can tell your workspaces apart. We suggest naming it like this:

```
aeonut-<workspace-slug>
```

| Rule | Why |
| - | - |
| Lowercase letters, numbers and hyphens only | Some clients reject or rewrite spaces and special characters in tool names |
| Always start with `aeonut-` | Groups your AeoNut workspaces together and separates them from other connectors |
| Slug is the brand or client name | Stays correct when the plan changes |
| Slug at most 20 characters | Some clients cap the full tool name at 64 characters, and at 20 the longest AeoNut tool name still fits |
| Never a plan name, environment or person | Those change, and the name becomes misleading |

| Workspace | Connector name |
| - | - |
| Acme Corp | `aeonut-acme` |
| Acme India | `aeonut-acme-in` |
| Globex (agency client) | `aeonut-globex` |

<Warning>
  Names like `Other`, `Scale workspace` and `test` are usually how an assistant ends up in the wrong workspace, so it's worth renaming each one to something like `aeonut-acme` or `aeonut-globex`.
</Warning>

### Asking about one workspace

It helps to name the workspace when you ask, like "check usage in acme". If you don't, an assistant with several connectors might query all of them and label the results by workspace.

## Try asking

* "How visible is our brand in AI answers this month compared to last month?"
* "Which competitors get cited more than us, and for which prompts?"
* "Why isn't our site cited for our top prompts? Look at the answers."
* "Which topics in our content map have gaps we haven't written about?"

## Next steps

<CardGroup cols={2}>
  <Card title="Using the MCP server" icon="lightbulb" href="/mcp/guide">
    What to ask, the ready-made analyses, and the workflows that get the most out of your data.
  </Card>

  <Card title="Tool reference" icon="list" href="/mcp/tools">
    Every tool, its inputs and what it returns.
  </Card>
</CardGroup>

## Troubleshooting

| Problem | Fix |
| - | - |
| My assistant queried the wrong workspace | Its connectors have vague or similar names. Rename each to `aeonut-<workspace-slug>`, then restart the client or reconnect so it picks up the new tool names. |
| The server won't connect | Check the header is `Authorization: Bearer YOUR_API_KEY` and the key hasn't been revoked or expired. |
| Some tools are missing | The key lacks that scope. Create a key with the scopes you need. |
| Claude's connector dialog says "Sign in now · Detected" | Ignore it and pick **No sign-in**. The server takes an API key, not OAuth. |
| VS Code ignores the header | You put it in `.mcp.json`. Use `.vscode/mcp.json` or the user configuration. |
| ChatGPT connectors | Not supported yet, because ChatGPT only accepts OAuth or open servers and never an API key. See [Not yet: ChatGPT](#not-yet-chatgpt). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.