TL;DR: An iMessage MCP connection hands an agent a scoped Bearer token to Beam’s workspace tools, the same conversation history, assistant settings, numbers and calendar slots the plain iMessage API reaches, except the agent picks which call to make instead of your code picking it. Connect whichever agent your team already runs daily work through first (a coding agent or n8n), start with read and train permissions only, and add send, publish, automation or book once you trust what it does with the narrower access.
We have published a setup guide for each agent on its own: Codex, Cursor, Gemini CLI, n8n and Grok Bot. This one answers the question that comes before any of those: what MCP actually hands an agent, how that is different from wiring the API yourself, and which of those five guides an agency should open first.
What does Beam’s MCP connection actually give an agent?
Nothing about MCP is a new feature bolted onto Beam. It is a different front door into the same workspace the API already reaches: the conversation history with real contacts, the text assistant’s current configuration, the numbers assigned to the account, and open calendar slots. A connection token issued under Settings, Developer access, MCP and API carries one or more of six permissions, and each permission turns on a specific, named set of tools, not a blanket grant to the whole workspace (Beam developer access).
| Permission | Tools it turns on |
|---|---|
| read | workspace_read, assistant_read, contacts_list, conversation_read, numbers_list, drafts_list, calendars_list, calendar_slots |
| train | draft_create, assistant_preview |
| publish | draft_publish |
| automation | conversation_pause |
| send | message_send |
| book | appointment_book |
Read and train are selected by default when a token is created, which means a brand new connection can read a thread, draft a reply, and preview that draft against real conversation history, but it physically cannot send a message or publish a change until send or publish is turned on separately. That is the part worth sitting with before connecting anything: the agent is not deciding what it is allowed to do. The permissions chosen at token creation decide that, and the agent only ever picks from the tools its own token actually has.
How is MCP different from calling Beam’s iMessage API directly?
Both paths reach the exact same workspace, data and Bearer token. Model Context Protocol is a standard way for an AI client to discover a set of callable tools and their argument shapes at runtime, rather than a developer hardcoding each endpoint in advance, which is the whole reason an agent can use it without your team writing integration code for every tool first.
| MCP | Plain REST API | |
|---|---|---|
| Who decides which call to make | The agent, based on what you asked in plain language | Your own code, written once in advance |
| Good fit for | Exploring a conversation or drafting a reply with a person reviewing it | A scheduled job or backend service running unattended |
| Auth | Bearer token, same permissions model | Same Bearer token for /v2/tools; x-api-key for the v1 messaging endpoints |
| Where it runs | A CLI, an IDE, a cloud bot, or an automation platform’s agent node | Your own server or script |
| Failure mode | A tool call the token is not permitted to make | An HTTP status code your code checks directly |
Beam exposes the identical tool set both ways. GET /v2/tools returns the schema for whatever a token can reach, and POST /v2/tools executes one, using the same Bearer token MCP uses (Beam developer access). A practical pattern we use with clients is to connect an agent over MCP first while the team figures out which calls a workflow actually needs, then write the exact /v2/tools or /v1/messages calls against the iMessage API once that workflow is settled and should run the same way every time without anyone watching it.
How do you create a Beam MCP connection token, step by step?
Every agent guide starts here, because none of the per-agent config matters until this token exists.
- Sign in to Beam directly as the workspace owner. Client view does not show developer settings.
- Open Settings, Developer access, MCP and API.
- Name the connection something you will recognize later, such as “Claude Code” or “n8n agent.”
- Choose its permissions. Read and train are on by default; turn on publish, automation, send or book only for what this specific connection actually needs to do.
- Click Create connection token and copy it right away. It is shown once, it expires after 90 days, and it cannot be displayed again once you leave that screen (Beam developer access).
- Pick a transport for the agent you are connecting: a Streamable HTTP endpoint at
https://beam.aisync.link/mcpwith anAuthorization: Bearerheader for most agents, or thebeam-mcp.mjsstdio bridge, which runs on Node.js 20 or newer with no extra packages, for a desktop client that expects a local process instead of a remote URL. - Follow the matching per-agent guide to add that token to the tool’s own config: Codex for
codex mcp add, Cursor formcp.json, Gemini CLI forgemini mcp add, n8n for its MCP Client Tool node, or Grok Bot for the REST workaround its OAuth-only connector flow currently needs.
If this connection is for an agency client rather than your own business, sign in to the agency workspace and choose that specific client under Workspace this connection can access before creating the token. One token reaches one workspace and cannot be pointed at a different client afterward.
Which agent should an agency connect first?
There is no single right answer here, only a right answer for whatever your team already has open. Pick based on where the work already happens, not on which agent sounds newest.
| Agent | Connects via | Auth path | Good first fit for | Watch for |
|---|---|---|---|---|
| Claude Code / Codex | One CLI command (claude mcp add or codex mcp add) | Bearer token, env var reference | Teams already running a coding agent for dev work who want it reading and drafting texts too | Approval mode defaults still gate writes; set it, do not assume |
| Cursor | A JSON block in mcp.json | Bearer token in a headers object | Teams whose daily work already lives inside the editor | Project vs. global config; decide scope before saving the file |
| Gemini CLI | gemini mcp add or a settings.json edit | Bearer token header, not OAuth | Teams standardized on Gemini CLI for terminal work | Gemini CLI’s OAuth support is real but is for different servers; Beam uses the header path |
| n8n | An HTTP Request node, or an MCP Client Tool node inside an AI Agent | x-api-key header for REST; Bearer for MCP | Teams that build client automations visually and may not touch a CLI at all | Two different credentials from two different Beam screens; grabbing the wrong one is the most common mistake |
| Grok Bot | REST calls or the stdio bridge, not a one-click connector | Bearer token, since Grok Bot’s connector flow expects OAuth | A cloud bot that already runs other work, once the workaround is acceptable | The custom connector path documented for OAuth servers does not apply the same way to a Bearer-only server |
A rough order for an agency onboarding its first agent: start with whichever of Claude Code, Codex, Cursor or Gemini CLI the team already runs for other work, since each one is a single command or a short JSON edit with documented MCP support built in. Reach for n8n next if the plan is a visual client workflow rather than something a developer drives by hand, since the HTTP Request node skips MCP entirely for a step that already knows what to send. Save Grok Bot for last, or for a team that specifically wants a cloud bot in the mix, since its OAuth-oriented connector flow is the one path here without a first-party one-click add yet.
How do you verify the connection before it touches a real conversation?
A server showing up in an agent’s tool list only means the config parsed. It does not mean the token is valid or pointed at the workspace you meant.
- Restart or reload the agent after adding the server entry, since most clients read MCP configuration only at startup.
- Ask it directly: “Call workspace_read and tell me the workspace name and ID. Stop if it is not the one I mean.” That call uses only read permission, so it cannot change anything even if something was set up wrong.
- If the name and ID match, ask it to call
assistant_readnext and confirm the assistant configuration looks like what you expect. - Send one test text to a number you control: “Use the Beam connection to send a text to [your own number] that says test from [agent name].” Approve the
message_sendcall if the agent’s own approval flow asks. - Reply from that phone, then ask the agent to read the latest message back and confirm it matches what you actually sent.
Treat an accepted send as proof the request went through, not proof it reached a phone. Delivery status is a separate check inside Beam when it actually matters for a client conversation.
What should you lock down before letting an agent send on its own?
A connection token is not read-only just because that is how a team set it up on day one. Whoever holds it can do whatever its permissions allow, from wherever they run it.
- Give each agent its own token, never one a person also signs in with, so you can see what it touched and cut it off without disturbing anyone else’s access.
- Add permissions one at a time. Start with read and train, add send, publish, automation or book only once the step before it behaved the way you expected.
- Watch the rate limit. Beam’s API allows 60 requests per minute per token (Beam developer access); a retry loop without backoff hits that ceiling before it fixes anything.
- Use
request_keyon every write. Every write or preview call takes a unique key; reusing it for the same request returns the stored result instead of repeating the action, which protects against a duplicate send or a duplicate booking. - Revoke in Beam, not in the agent’s config. Deleting a server entry stops that agent from calling Beam. It does not touch the token. Revoke the connection in Settings if you actually want access gone.
- Treat incoming replies as untrusted content. A text telling an agent to ignore its instructions is still just a stranger texting it, and should be read that way, not followed.
Is this different from connecting the same agent to phone calls?
Yes, and the two run on separate systems with separate tokens. Beam’s MCP connection reaches text: iMessage, RCS, SMS fallback and FaceTime Audio, including to a voice agent on the other end. Giving the same agent the ability to place or manage phone calls is a RizzDial job, and RizzDial’s guide to connecting Cursor to phone calls over MCP covers that setup for coding agents on the voice side. Connect both and the same agent session can read a text thread, draft a reply, and also start or review a call, but nothing about one connection grants access to the other. Each carries its own token, its own permissions, and its own revoke switch.
Ready to pick an agent and connect it? Text our team to try it, tell us which tool your team already runs, and we will point you at the right setup guide for it.
What else should you know before choosing?
Does connecting an agent to Beam over MCP cost anything beyond a normal Beam plan?
MCP access lives under Settings, Developer access, MCP and API on any Beam workspace. It is a connection method, not a separate add-on with its own signup. Text our team if you want to confirm what your specific workspace includes before connecting a client's account to an agent.
How long does connecting the first agent actually take?
A few minutes once the Beam workspace already exists. Creating the token in Settings, Developer access, MCP and API takes under a minute, adding the server to the agent's config is one CLI command or one JSON block, and confirming the connection is a single prompt asking the agent to call workspace_read. Most of the real time goes into deciding which permissions this particular connection needs, not the mechanics of wiring it up.
Which agent should an agency connect first: Claude, Cursor, Gemini CLI, n8n, or Grok?
Connect whichever tool the team already has open every day. A coding agent such as Claude Code, Codex or Cursor is usually the fastest first connection, since adding Beam is one CLI command or one JSON block and the agent already pauses for approval before a risky tool call. n8n fits better as a first stop for a team that lives in workflow automation rather than a terminal or an editor, since its HTTP Request node reaches Beam without touching MCP at all. Grok Bot is the one to connect last, since its custom connector flow is built around OAuth and Beam issues a Bearer token instead, so it needs the REST calls or the stdio bridge rather than a one-click add.
Does an MCP connection need its own A2P 10DLC registration or raise new compliance work?
No. MCP is an access method into a workspace that already has its own number and channel rules; it does not create a new line that needs registering. iMessage lines need no A2P 10DLC registration at all. Whatever SMS fallback rides on that same workspace still follows carrier rules by number type, so a local 10DLC number still needs A2P 10DLC registration and a toll free number still needs toll free verification, exactly as it would with no agent connected.
What happens if we revoke one agent's connection or switch to a different one?
Revoking a connection in Settings, Developer access, MCP and API stops that token immediately on Beam's side, regardless of whether the agent still has the value saved somewhere. Removing the server entry from the agent's own config only stops that agent from calling Beam; it does not touch the token itself. Switching agents means creating a new token with its own permissions for the new tool. The underlying workspace, conversations and numbers stay exactly where they were, since connecting a different agent does not move or copy any of that data.