MCP Server

Broadcast has a built-in Model Context Protocol (MCP) server. Point an MCP client such as Claude Code at your instance and your API operations become tools the AI can call directly: look up a subscriber, draft a broadcast, check delivery stats, or manage users.

There is nothing to install. The server is part of Broadcast itself, at /api/mcp on your instance, and it uses the same API tokens as the REST API.

What you need

• Your Broadcast URL, for example https://broadcast.example.com
• An API token. A channel token works on one channel; an admin API token can reach every channel and is the only way to manage users. See API Authentication.
• An MCP client that supports remote (HTTP) servers and lets you set a request header, such as Claude Code

Connect Claude Code

Run this once, replacing the URL and token:

claude mcp add --transport http broadcast https://broadcast.example.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Then start Claude Code and run /mcp to confirm the broadcast server is connected.

By default the server is added for the current project on your machine only. Add --scope user to make it available in every project.

Connect other clients

Any MCP client that supports remote HTTP servers with custom headers can connect. Most accept a configuration in this shape; check your client’s documentation for the exact file and field names:

{
  "mcpServers": {
    "broadcast": {
      "type": "http",
      "url": "https://broadcast.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

The server speaks the Streamable HTTP transport in stateless mode: every request is a single POST to /api/mcp, and no session is kept between requests.

Which tools you get

Tools are generated from Broadcast’s API, so they always match the version you are running. Each tool is one API operation, named after it: subscribers_find, broadcasts_create, broadcasts_send_broadcast, users_channel_permissions_bulk, and so on. Each tool’s description and input schema come from the API reference.

What a client sees depends on the token:

• Discovery tools are always available: whoami_show, status_show and prime_show. Asking the AI to call prime_show first is a good way to let it learn what it can do.
• Resource tools follow the token’s permissions. Read permission gives the tools that list and fetch; write permission gives the tools that create, change and delete. A token with only Subscribers access sees only subscriber tools.
• Admin-only tools appear only for admin API tokens: the Users API and the global suppression list.

A channel token with every permission sees 90 tools; an admin API token with every permission sees 108.

Admin API tokens

An admin API token is not tied to a channel. Tools that act on a channel take a required broadcast_channel_id argument; the AI will ask for it or look it up. User and global suppression tools do not need it.

Safety

The MCP server can only do what the API allows for the token it was given, and every tool call goes through the API’s normal checks:

• Destructive tools are marked. Sending or scheduling a broadcast, deleting anything, deactivating, unsubscribing and redacting are flagged as destructive, so clients that support it ask you before running them. The server also instructs the AI to confirm with you first.
• Refusals come back as errors, not silence. If the API rejects a call, for example because it would change a sudo user, the tool result is an error carrying the API’s message, which the AI can report to you.
• Sudo users are read-only through the MCP server, exactly as through the API.

Rate limits

Each tool call counts once against the token’s rate limit, even though it makes an API request behind the scenes. The limit is the token’s own, if you set one, or the installation default. To give an AI agent more headroom, set a higher rate limit on the token it uses. See API Authentication.

Troubleshooting

The server does not connect

Check that your instance runs Broadcast 2.35.0 or later, and that the URL ends in /api/mcp. You can test the endpoint and your token directly:

curl -X POST https://broadcast.example.com/api/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A list of tools means the server and token are working, and the problem is in the client configuration.

401 Unauthorized

The token is missing, invalid or expired. Make sure the header is exactly Authorization: Bearer YOUR_API_TOKEN.

403 Forbidden

The request came from a browser page on another site. The MCP server refuses cross-origin browser requests. Desktop and command-line clients do not send an Origin header and are not affected.

405 Method Not Allowed

The client tried to open a GET stream or a session. The server only answers POST; configure the client for Streamable HTTP rather than the older SSE transport.

A tool you expected is missing

The token does not have the permission for it, or the tool is admin-only and you are using a channel token. Call whoami_show to see the token’s permissions, and edit the token to add what is missing.

A tool call fails because broadcast_channel_id is missing

You are using an admin API token, and the tool acts on a channel. Pass broadcast_channel_id for the channel you mean, or use a channel token for work on a single channel.