# MCP Server

> Connect Claude Code and other MCP clients to Broadcast's built-in MCP server. No install: point your client at your instance's /api/mcp URL with an API token, and every API operation your token allows becomes a tool.

Source: https://sendbroadcast.net/docs/agents-mcp

Broadcast has a built-in [Model Context Protocol](https://modelcontextprotocol.io) (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.

Note

**Requires Broadcast 2.35.0 or later.** Earlier versions do not have the `/api/mcp` endpoint and answer `404`. Check your version at the bottom of the sidebar.

## 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](https://sendbroadcast.net/docs/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:

```bash
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.

Warning

**Keep the token out of version control.** `--scope project` writes the server, including the `Authorization` header, to a `.mcp.json` file in your repository. Only use project scope if that file is never committed.

## 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:

```json
{
  "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](https://sendbroadcast.net/docs/api-users) 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.

Warning

Give the MCP server the smallest token that does the job. A token with only read permissions cannot change anything, whatever the AI decides to do.

## 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](https://sendbroadcast.net/docs/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:

```bash
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.