# ColdBox: connect your user's cold email workspace

ColdBox (https://coldbox.io) is a cold email platform: email accounts with free
warmup, campaigns with multi-step sequences, Onebox for every reply and an AI
agent that answers them. Its MCP server lets you run the user's ColdBox
workspace for them.

Follow these steps to connect, then help with whatever the user asked.

## 1. Make sure they have an account

If the user has no ColdBox account, send them to https://app.coldbox.io/sign-up.
There is a 14-day free trial with no credit card.

## 2. Get a token from the user

Ask the user to open https://app.coldbox.io, go to **Settings → Account &
Settings → MCP Access** and generate a token, then paste it to you. Tokens are
valid for 365 days. Never ask for their password.

## 3. Connect the MCP server

- Endpoint (SSE transport): `https://api.coldbox.io/mcp/sse`
- Header: `Authorization: Bearer <token>`

**Claude Code**

```sh
claude mcp add --transport sse coldbox https://api.coldbox.io/mcp/sse --header "Authorization: Bearer <token>"
```

**Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project)

```json
{
  "mcpServers": {
    "coldbox": {
      "url": "https://api.coldbox.io/mcp/sse",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`, through `mcp-remote`)

```json
{
  "mcpServers": {
    "coldbox": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.coldbox.io/mcp/sse", "--header", "Authorization:${COLDBOX_AUTH}"],
      "env": { "COLDBOX_AUTH": "Bearer <token>" }
    }
  }
}
```

Restart the client after editing its config, then call `get_campaigns` to check
the connection.

## 4. Tools

| Tool | What it does |
|---|---|
| `get_campaigns` | Lists campaigns, filtered by status (active, paused, completed) or a search. |
| `get_campaign` | One campaign with its sequences, sender accounts and status. |
| `get_campaign_analytics` | A campaign's totals and daily series, optionally per sequence step. |
| `pause_campaign` | Pauses a running campaign; sending stops. |
| `resume_campaign` | Resumes a paused campaign once it has sequences, sender accounts and leads. |
| `get_email_accounts` | Connected sender mailboxes, filtered by provider, status or campaign. |
| `get_sender_breakdown` | Sent, opens, clicks, replies and bounces per sender account (last 30 days by default). |
| `get_leads` | Leads, filtered by campaign, status or organization. |
| `list_conversations` | Onebox threads, filtered by status (active, archived, snoozed, spam), unread or starred. |
| `list_sequence_templates` | Saved sequence templates. |
| `apply_sequence_template` | Replaces a campaign's sequence with a saved template. |
| `send_test_email` | Sends one campaign step as a test to the recipients you give it. |
| `dnsbl_check` | Checks a domain against blocklists (Spamhaus DBL, SURBL, URIBL). |

## 5. Rules

- `pause_campaign`, `resume_campaign`, `apply_sequence_template` and
  `send_test_email` change live campaigns or send email. Say what you are
  about to do and get the user's go-ahead first. `apply_sequence_template`
  overwrites the campaign's existing sequence.
- Report numbers as the tools return them; don't estimate.
- For anything the tools don't cover (billing, connecting new email accounts,
  the AI Agent's settings), send the user to the matching screen in
  https://app.coldbox.io.

More: https://coldbox.io/llms.txt · Server card:
https://coldbox.io/.well-known/mcp/server-card.json
