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

# Overview

> Connect AI clients to an Aimtell account with the Aimtell MCP server

The Aimtell MCP server exposes an Aimtell account to AI clients through the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP client, such as Claude, Cursor, Windsurf or your own agent, can use it to look up sites, campaigns, segments, subscribers and analytics, and to prepare campaigns and segments on the account's behalf.

It is a hosted, remote server built on the REST API. It wraps a curated set of 21 tools rather than every REST endpoint, so a model has fewer, clearer choices to make. See [Tools](/mcp-server/tools) for the full list.

| Setting | Value |
| - | - |
| Endpoint | `https://mcp.aimtell.com/mcp` |
| Transport | Streamable HTTP (stateless) |
| Authentication | Aimtell API key, sent as a bearer token |

## Authentication

Every request must carry the account's API key, which is generated within the Dashboard under **API Keys**. Send it in either header:

| Header | Value |
| - | - |
| Authorization | `Bearer <AIMTELL_API_KEY>` |
| X-Aimtell-Api-Key | `<AIMTELL_API_KEY>` |

The server forwards the key to the REST API on each call and never stores it. Each request is handled in isolation with its own key, so one connection never sees another account's data.

Clients that cannot set a header, such as the Claude.ai and Claude Desktop connector, connect through OAuth instead. The server shows a page asking for the API key, and that key becomes the client's access token. The key is sealed in transit during the handshake and is not stored.

## Connecting a Client

### Claude.ai and Claude Desktop

Open **Settings**, go to **Connectors**, choose **Add custom connector** and enter `https://mcp.aimtell.com/mcp`. Claude opens the **Connect your Aimtell account** page, where the API key is pasted once.

### Claude Code

```bash theme={null}
claude mcp add --transport http aimtell https://mcp.aimtell.com/mcp \
  --header "Authorization: Bearer YOUR_AIMTELL_API_KEY"
```

### Cursor, Windsurf and Other Clients

Add the server to the client's MCP configuration, such as `mcp.json` in Cursor:

```json theme={null}
{
  "mcpServers": {
    "aimtell": {
      "url": "https://mcp.aimtell.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_AIMTELL_API_KEY" }
    }
  }
}
```

### Raw JSON-RPC

The server speaks standard MCP over HTTP, so it can also be called directly. Requests must accept both `application/json` and `text/event-stream`.

```bash theme={null}
curl -X POST https://mcp.aimtell.com/mcp \
  -H "Authorization: Bearer YOUR_AIMTELL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_sites","arguments":{}}}'
```

## Confirming Writes

Every tool that creates or changes something takes an optional `confirm` argument and runs in two steps:

1. **Call without `confirm`.** Nothing is written. The tool returns a plain-language summary of exactly what would happen, ending in a confirmation token.
2. **Call again with identical arguments plus `confirm` set to that token.** The change goes through.

The token is derived from the arguments themselves, so changing any argument invalidates it and the tool returns a fresh preview instead. Clients should show the preview to the user and get their approval before making the second call.

This applies to all eight write tools: `create_campaign`, `create_draft_campaign`, `create_draft_triggered_campaign`, `create_draft_rss_campaign`, `update_draft`, `upsert_welcome_campaign`, `create_segment` and `track_subscriber_attribute`.

## Sending Safeguards

<Warning>
  There is no immediate-send tool. A push can only go out through `create_campaign` with a future `schedule_date` and `status` set to `2`, so every send stays visible and cancellable in the dashboard until it fires.
</Warning>

* `create_campaign` defaults `status` to `1` (draft), so omitting it never sends.
* The `create_draft_*` tools take no `status` argument and always save a draft.
* `update_draft` only changes campaigns that are still drafts, refuses A/B test drafts, and takes no `status` or `schedule_date`, so it can never schedule or send a campaign.
* Triggered and RSS drafts must be activated in the dashboard.

## Errors

Failed calls return an MCP tool error carrying the REST API's HTTP status and message. Upstream response bodies are not passed through.


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