# Connect an AI agent (MCP) > Connect Claude Code or another MCP client to Broadcast's built-in MCP server, choose a safe token, and let an agent work on your email marketing. Source: https://sendbroadcast.net/university/developers/connect-ai-agent-mcp An AI agent can do in a minute what takes you ten clicks: find a subscriber, draft a broadcast, check last week's stats. In this lesson you connect one through Broadcast's built-in MCP server, and you set it up so the agent can only do what you allow. ## Three ways in Broadcast gives agents three routes, and they all use the same API tokens: 1. **The MCP server**, at `/api/mcp` on your installation. Every API operation the token allows becomes a native tool. Best for Claude Code and other MCP clients. 2. **The `broadcast` CLI**, for agents that run shell commands. The previous lesson covered it. 3. **The REST API**, with discovery endpoints `GET /api/v1/whoami`, `/status` and `/prime` that tell an agent what it can do. ### MCP server `/api/mcp` - Best for MCP clients - Nothing to install ### `broadcast` CLI Shell commands - For agents that run a shell ### REST API `/api/v1` - Discovery with `whoami`, `status` and `prime` All three routes use the same API tokens. This lesson focuses on MCP. There is nothing to install: the server is part of Broadcast. It needs Broadcast 2.35.0 or later. ## Step 1: Choose the token first The token decides everything the agent can do. Pick it before you connect: - **A read-only channel token** for an agent that answers questions: stats, counts, subscriber lookups. It cannot change anything, whatever the agent decides to do. - **A channel token with specific write permissions** for an agent that drafts broadcasts or tags subscribers in one channel. - **An admin API token** only when the agent must work across channels or manage users. Tools that act on a channel then need a `broadcast_channel_id`. - Read-only channel token: reads one channel: Least - Channel token with write permissions: changes what you ticked, in one channel: More - Admin API token: every channel, and users: Most How far each token reaches. Pick the shortest bar that does the job. Create the token under **Access Tokens** and tick only what the job needs. Agents can make many calls quickly. If the agent hits the limit, raise the **Rate limit** on that token, not the default for the whole installation. Each MCP tool call counts once against the limit. ## Step 2: Connect Claude Code Run this once: ```bash claude mcp add --transport http broadcast https://broadcast.example.com/api/mcp \ --header "Authorization: Bearer YOUR_API_TOKEN" ``` Start Claude Code and run `/mcp` to check that the `broadcast` server is connected. By default the server is added for the current project on your machine only. Add `--scope user` to use it in every project. Warning Do not use `--scope project` unless the file stays out of your repository. It writes the server, with the `Authorization` header and your token, to `.mcp.json`. Other MCP clients that support remote HTTP servers with custom headers connect the same way: the URL `https://your-domain/api/mcp`, type `http`, and an `Authorization: Bearer` header. The server uses the Streamable HTTP transport, one `POST` per request, with no session. ## Step 3: Let the agent find its way The tools are generated from your installation's API, so they match the version you run. Each tool is one operation, with a name such as `subscribers_find` or `broadcasts_create`. Three discovery tools are always there: `whoami_show`, `status_show` and `prime_show`. Start a session by asking the agent to call `prime_show`. It learns the token's permissions, the channel's status and every available operation. Then ask in plain language: - "Find ada@example.com and show her tags." - "Draft a broadcast to the Engaged segment that announces our new pricing page. Do not send it." - "Compare the click rates of our last five broadcasts." ## The safety rails The MCP server can do only what the API allows for its token, and every call goes through the API's normal checks. 1. **Agent** Calls a tool 2. **MCP server** Part of Broadcast 3. **API checks** Token, permissions, limits 4. **Result** Or an error message The agent has no route around the API. A refused call comes back as an error with the reason. Destructive tools are marked as such: sending or scheduling a broadcast, deleting, deactivating, unsubscribing and redacting. Clients that support it ask you before they run one, and the server tells the agent to confirm with you first. Still, read what the agent proposes before you approve a send. A sent email cannot be recalled. A refused call comes back as an error with the API's message, so the agent can tell you what went wrong instead of failing without a word. ## Other ways to hand over credentials You do not always want to paste a token into a chat. The **Agents** page in your dashboard offers two other routes: - A **copy-paste introduction message** with your instance URL, token, permissions and quick-start commands. - A **setup link**: a URL that serves the agent its configuration. It expires after 1 hour and works only 3 times, so it is safe to share in a conversation. ![The Agents page with an Introduction Message card holding the host, token, channel, quick-start commands and permissions, with a Copy button](https://sendbroadcast.net/assets/docs/university/agents-page-2e82471f.png) The introduction message on the Agents page. It uses your real host and token. This example shows placeholders. ## When it does not connect 1. Check that the URL ends in `/api/mcp` and that you run 2.35.0 or later. Older versions answer `404`. 2. A `401` means the token or the header is wrong. The header must be exactly `Authorization: Bearer YOUR_API_TOKEN`. 3. A `405` means the client tried an older SSE transport. Set it to Streamable HTTP. 4. A missing tool means the token lacks that permission. Ask the agent to call `whoami_show` to see what the token has. See [MCP server](/docs/agents-mcp) and [Agents](/docs/agents). ## What you learned - The MCP server is built in at `/api/mcp` and uses your normal API tokens. - The token sets the limits. A read-only token cannot change anything. - Start with `prime_show` so the agent learns what it can do. - Destructive tools are marked, and you approve sends. Keep tokens out of `.mcp.json` in git. ## Quiz 1. What do you install on your server to run the Broadcast MCP server? - A separate MCP package from npm - A Docker sidecar container - Nothing, it is built into Broadcast at /api/mcp (correct) The MCP server is part of Broadcast itself, at /api/mcp, and uses the same API tokens as the REST API. 2. Which tools does an MCP client see? - Tools that match the token's permissions, plus the discovery tools (correct) - Every tool, whatever the token - Only read-only tools - Only the tools you list in the client config Resource tools follow the token's read and write permissions. Discovery tools are always there, and admin-only tools need an admin token. 3. Why should you avoid --scope project when you add the server in Claude Code? - It makes the server slower - It writes the token into a .mcp.json file that can end up in version control (correct) - It only works for admin tokens Project scope writes the server, including the Authorization header, to .mcp.json in your repository.