AI assistants (MCP)

relaybell-mcp is an MCP 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 18 or newer, and an API key for the website you want the assistant to use (one key = one website).

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:

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.

Add it to your assistant

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

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.

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

Claude Code

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

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

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

{
  "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

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:

{
  "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

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 under "mcpServers", save, and refresh the MCP panel.

Other assistants

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

• "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

Read

These never change anything.

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

Act

What it can't do

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

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.

Settings

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.
• "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.