AI agents: the SendBeam MCP server

If you work in an AI coding assistant or an agent, SendBeam can be one of its tools. The MCP server turns the HTTP API into tools the agent can call by name — list contacts, create a tag, draft a campaign, read a report — with the workspace and permissions of the API key you connect it with.

What it is

A Model Context Protocol server over Streamable HTTP at https://sendbeam.io/api/v1/mcp. There is nothing to install and nothing to run: point a client at the URL with a workspace API key as the bearer token. Every request stands on its own, so there is no session to keep alive.

The server is switched on per workspace while it settles. If your workspace does not have it yet, the URL answers 404; ask us at contact.

The key decides what the agent can do

Create a key under Settings → API keys and choose its permissions with the agent in mind. The agent is only offered the tools those permissions allow, and every call runs through the same checks as a direct API request: a key without campaigns:send cannot send, a key without contacts:write cannot change a contact, and no key can see another workspace. A good starting point is read permissions plus campaigns:write and templates:write, so the agent can draft but not send. Add campaigns:send only when you want it to.

Tools that send email, activate an automation, delete, import or suppress are marked as needing confirmation. Well-behaved clients ask you before calling them; the server also tells the agent to.

Claude.ai and Claude Desktop

These sign in rather than take a key. Add a custom connector with the URL https://sendbeam.io/api/v1/mcp; Claude opens SendBeam, where you sign in, choose the workspace and tick what the connection may do. That creates a key under Settings → API keys named after the app: the connection is that key, and deleting it disconnects the app. Connecting again replaces it.

Claude Code

One command, with your key:

claude mcp add --transport http sendbeam https://sendbeam.io/api/v1/mcp \
  --header "Authorization: Bearer sb_live_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"

Then, in a session, ask for what you want: “How many contacts joined the newsletter list this week?” or “Draft a campaign to the Customers segment announcing the autumn range; don't send it.” Run /mcp to see the connection and the tools it offers.

Cursor, VS Code and others

Any client that supports remote MCP servers over HTTP takes the same URL and header. In Cursor, add to .cursor/mcp.json:

{
  "mcpServers": {
    "sendbeam": {
      "url": "https://sendbeam.io/api/v1/mcp",
      "headers": { "Authorization": "Bearer sb_live_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" }
    }
  }
}

VS Code (.vscode/mcp.json) uses the same shape with "type": "http". Keep the key out of source control: most clients can read it from an environment variable or their own secret store.

Clients that only speak stdio

A client that launches servers as local processes can reach the same endpoint through the standard bridge:

npx -y mcp-remote https://sendbeam.io/api/v1/mcp \
  --header "Authorization:Bearer ${SENDBEAM_API_KEY}"

Put that as the server command in the client's configuration, with SENDBEAM_API_KEY in its environment.

What the agent sees

One tool per operation in the API reference, named after the operation — listContacts, createTag, getCampaignStats, sendCampaign — with the operation's path, query and body fields as one set of arguments and the same descriptions. Because the tools are generated from the same document as the reference, they can never drift from it; anything new in the API is a tool the next time the agent lists them. Operations that take a file (CSV import, image upload) and the account-level and sign-in routes are not offered.

Results come back as the API's JSON. Lists are paged: the agent passes page and limit exactly as a script would, and a very long result is cut with a note to ask for a smaller page.

Limits and good habits

• Writes count the same. A tool that writes spends the key's hourly write allowance for the plan, like any API call. Reads are unmetered.
• One workspace per key. To let an agent work across several sites, connect one server per workspace, each with its own key, under different names.
• Revoke to disconnect. Deleting the key under Settings → API keys ends the agent's access at once.
• Prefer drafts. Let the agent create campaigns and automations as drafts and review them in SendBeam before sending or activating.