[relaybell docs › Developers › AI assistants (MCP)](https://relaybell.com/docs/ai-assistants) · [All docs as Markdown](https://relaybell.com/docs.md) · [Index for AI assistants](https://relaybell.com/llms.txt)

# AI assistants (MCP)

> Connect Claude, Cursor, VS Code or Windsurf to relaybell with the relaybell-mcp server, so your assistant can read your results and send notifications after you confirm.

`relaybell-mcp` is an [MCP](https://modelcontextprotocol.io) server: a small program your AI assistant runs on your computer to use relaybell. Once it's added, you can ask things like "How did last week's notifications do?" or "Draft a notification for the winter sale and send me a test", and the assistant looks up your real numbers and does the work.

It works with Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot agent mode), Windsurf and any other assistant that supports MCP servers. It needs [Node.js](https://nodejs.org) 18 or newer, and an API key for the website you want the assistant to use (one key = one website).

> **Note:** Sending to your subscribers always takes two steps: the assistant shows you a summary of exactly what will go out and to how many devices, and sends only after you say yes. See [The two-step send](https://relaybell.com/docs/ai-assistants#two-step-send).

## Create a key {#create-a-key}

In the dashboard, open **Settings → Developers** and click **Create a key for your assistant**. It opens the usual create-key dialog with the name "AI assistant" and these permissions ticked:

| Permission | What the assistant uses it for |
| --- | --- |
| Send notifications (`send`) | Send and cancel notifications |
| Edit segments (`segments:write`) | Save a new segment |
| Report events (`events:write`) | Report an event for one person |
| Read subscribers (`subscribers:read`) | Look up one person, recent events and segment sizes |

After you create it, the card fills the key into the setup for Claude Desktop, Claude Code and Cursor, so you can copy it straight away (VS Code asks for it instead). The key is shown only once: if you leave the page, create a new one.

Don't give the assistant a **Full access** key: it doesn't need one. To let it read but never send or change anything, create a key with only **Read subscribers** and add `"RELAYBELL_READ_ONLY": "1"` next to the key in the setup below.

> **Warning:** The setup holds your API key. Keep it in your own settings, not in a file you commit to a repository. Revoke a key any time in **Settings → Developers → API keys**.

## Add it to your assistant {#setup}

Replace `YOUR_API_KEY` with your key (the dashboard card does this for you).

### Claude Desktop {#claude-desktop}

In Claude Desktop, open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`. Add relaybell, save, then quit Claude Desktop completely and open it again.

```json
{
  "mcpServers": {
    "relaybell": {
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Claude Code {#claude-code}

Run this once in a terminal. `--scope user` makes relaybell available in every project.

```bash
claude mcp add --env RELAYBELL_API_KEY=YOUR_API_KEY --transport stdio --scope user relaybell -- npx -y relaybell-mcp
```

On Windows (not WSL), start npx through `cmd /c`: end the command with `-- cmd /c npx -y relaybell-mcp`. Check that it's connected with `claude mcp list`, or `/mcp` inside Claude Code. Claude Code asks you before every `confirm_send`, even when other tools run without asking.

### Cursor {#cursor}

Put this in `~/.cursor/mcp.json` in your home folder (every project), or `.cursor/mcp.json` in one project:

```json
{
  "mcpServers": {
    "relaybell": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

In a project file, write `"RELAYBELL_API_KEY": "${env:RELAYBELL_API_KEY}"` instead, so the key comes from your environment and never sits in the repository.

### VS Code {#vscode}

Create `.vscode/mcp.json`. VS Code asks for the key the first time it starts relaybell and stores it securely, so the file never contains it:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "relaybell-api-key",
      "description": "relaybell API key",
      "password": true
    }
  ],
  "servers": {
    "relaybell": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "relaybell-mcp"],
      "env": {
        "RELAYBELL_API_KEY": "${input:relaybell-api-key}"
      }
    }
  }
}
```

Then use Copilot Chat in agent mode.

### Windsurf {#windsurf}

In Cascade, open the MCP servers panel and choose **View raw config** to open `mcp_config.json`. Add the same `relaybell` block as for [Claude Desktop](https://relaybell.com/docs/ai-assistants#claude-desktop) under `"mcpServers"`, save, and refresh the MCP panel.

### Other assistants {#other}

Any assistant that runs MCP servers over stdio works: the command is `npx`, the arguments are `-y relaybell-mcp`, and the key goes in the `RELAYBELL_API_KEY` environment variable.

## Try it {#try-it}

- "How are my notifications doing this month compared with last month?"
- "Which of my last 20 notifications had the best click rate, and what do they have in common?"
- "How many subscribers are in the US and have the label plan = pro?"
- "Draft a notification for the winter sale for my Returning buyers segment, send me a test, then schedule it for Friday at 9:00 New York time."
- "Why did yesterday's notification get so few clicks?"

relaybell-mcp also comes with two ready-made prompts, **draft_campaign** and **why_did_this_campaign_underperform**. In Claude Code they appear as `/relaybell:draft_campaign`.

## What the assistant can do {#tools}

### Read {#read-tools}

These never change anything.

| Tool | What it does |
| --- | --- |
| `get_project` | The website: name, address, subscribed devices, whether the code is installed, whether the account email is verified, and the sending rules. |
| `get_stats` | Sent, delivered, clicks, click-through rate, conversions and revenue for a date range, compared with the period before. |
| `list_segments` | Your segments and how many devices each matches now. |
| `preview_audience` | How many devices a segment, filters, a topic or a list of your user ids reach, with exclusions. |
| `list_topics` | Your topics and how many subscribers each has. |
| `list_automations` | Your automations and journeys, with their last-30-day results. It can't edit them. |
| `list_notifications` | Your notifications with their results, filtered by status, dates or words. |
| `get_notification` | One notification in detail: the funnel, devices, A/B variants, languages and delivery errors. |
| `get_subscriber` | One person's profile, looked up by the user id your site gave relaybell. |
| `list_recent_events` | The latest events your site or server reported. |

The assistant can also read the whole relaybell documentation and a list of every API endpoint.

### Act {#write-tools}

| Tool | What it does |
| --- | --- |
| `send_test_to_my_devices` | Sends a notification to your own test devices only, never to subscribers. Add a test device in the dashboard first: on the Send page, click the arrow next to **Send test**. |
| `create_segment` | Saves a new segment. It can't change or delete existing ones. |
| `track_event` | Reports an event (such as signup or purchase) for one person. It can start that person's automations, and a purchase with a value counts as revenue. |
| `cancel_notification` | Stops a scheduled notification before it goes out. Sent notifications can't be recalled. |
| `prepare_send` | Step 1 of a send: checks it and returns a summary. Sends nothing. |
| `confirm_send` | Step 2: sends exactly what was prepared, after you say yes. |

### What it can't do {#limits}

It can't create or revoke API keys, delete anything (subscribers, segments, notifications), change settings, rotate your identity-verification secret, or manage webhooks. The key's permissions apply on top: a key without **Send notifications** can't send, whatever the assistant tries.

## The two-step send {#two-step-send}

1. **Prepare.** `prepare_send` checks the title (up to 250 characters), the message, the link and image (full `https://` addresses), the audience and the timing: right away, at a set date and time (with a time zone, at most 90 days ahead), or at a time of day in each subscriber's own time zone. It counts how many devices the audience reaches now, and returns a plain summary and a confirmation token. Nothing is sent.
2. **You check the summary.** The assistant shows you the title, message, link, audience size and timing, and asks you to confirm.
3. **Confirm.** Only after your yes does the assistant call `confirm_send`, with the token and nothing else. It sends exactly what was prepared.

The confirmation token protects you from mistakes:

- It is tied to that exact send with a signature only this run of relaybell-mcp can make. A changed or made-up token is refused, and so is one from before the assistant restarted.
- It works once, and expires after 10 minutes.
- When it's used, the audience is counted again. If it changed by more than 20% (for example, a segment's rules were edited), nothing is sent and the assistant tells you why. Run the prepare step again to see the new numbers.
- A send with no audience is refused. To send to every subscriber, you have to say so, and the summary marks it as going to **every subscriber**. A segment without rules counts as everyone.

The usual send rules still apply: quiet hours, the hourly send limit, and the first-send review for new accounts. See [Errors and limits](https://relaybell.com/docs/errors-limits).

## Settings {#settings}

| Variable | Default | What it does |
| --- | --- | --- |
| `RELAYBELL_API_KEY` | required | Your API key. |
| `RELAYBELL_READ_ONLY` | off | `1` offers only the tools that read. |
| `RELAYBELL_BASE_URL` | `https://relaybell.com` | Only for a self-hosted or local relaybell. |

## Troubleshooting {#troubleshooting}

- **"RELAYBELL_API_KEY is not set".** The key isn't in the setup's `env` (or `--env` for Claude Code). Add it and restart the assistant.
- **"relaybell didn't accept this API key".** The key was revoked, has expired or was copied incompletely. Create a new one in **Settings → Developers**.
- **"This API key can't do that: it needs the 'send' permission".** Create a key with the [permissions above](https://relaybell.com/docs/ai-assistants#create-a-key).
- **"This relaybell account has not verified its email address yet".** Click the link in the verification email (check spam), or resend it from the banner in the dashboard. Test sends work meanwhile.
- **"Too many requests".** A key can make 60 requests a minute and 600 an hour, and each website has an hourly send limit. Wait a moment and try again.
- **"You don't have a test device yet".** In the dashboard, open **Send**, click the arrow next to **Send test** (Test devices), then open the private link on your own phone or computer and click **Allow**.
- **It doesn't start on Windows, or says "Connection closed".** Some assistants can't start `npx` directly on Windows. Use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "relaybell-mcp"]`. If `npx` isn't found, install Node.js 18 or newer and restart the assistant.
- **Claude Desktop shows nothing.** Quit it completely (also from the system tray on Windows) and open it again.