A protocol reference, from Beam's docs
Updated
iMessage MCP server: what it gives an agent
An iMessage MCP server lets an AI agent call a fixed set of tools, read a conversation, train a draft, send a message, book an appointment, against a real iMessage line through the Model Context Protocol, instead of you building custom glue code per client. Beam runs one at https://beam.aisync.link/mcp, reachable over bearer-token HTTP or a local stdio bridge.
What MCP means for iMessage
The Model Context Protocol is a standard, created by Anthropic, for connecting AI models to external tools and data. Its specification defines two standard transports: stdio, newline-delimited messages over a client-launched subprocess, and Streamable HTTP, where each message is an HTTP POST to a single endpoint. An iMessage MCP server simply exposes iMessage-related actions, reading a conversation, sending a message, pausing automation, through that same standard shape, so any compatible client can call it the same way it calls any other MCP server.
What an iMessage MCP server actually gives an agent
Rather than a single "send text" function, a well-built iMessage MCP server exposes the real operations a messaging workflow needs: reading the workspace and assistant configuration, listing contacts and conversations, checking calendar availability, drafting and previewing assistant changes before they go live, pausing automation for a specific thread, sending a message, and booking an appointment against a real calendar. Which of those an agent can call depends entirely on the permissions granted to its connection token.
Beam's MCP server: transports and endpoint
Beam documents two ways to connect:
- Streamable HTTP with a bearer token, at
https://beam.aisync.link/mcp, using anAuthorization: Bearer YOUR_TOKENheader. This is what Claude Code and similar HTTP-capable clients use. The endpoint is stateless and returns JSON responses. - A local stdio bridge for desktop clients that run MCP servers as a subprocess. Download Beam's bridge file, run it with Node.js 20 or newer, and point your client's configuration at the absolute path with your token in the environment.
Hosted connectors that require OAuth-only login are not supported in this release. See the Claude Code specific walkthrough for exact commands.
Full tool and permission catalog
| Permission | Tools |
|---|---|
| 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 granted by default on a new connection token. Publishing, automation, real sending and booking each require an explicit permission grant, independent of each other.
Which MCP clients are supported
Beam's own setup docs cover Claude Code (bearer HTTP, registered with claude mcp add), Claude Desktop and other stdio-capable clients (the local bridge), Cursor (its own private MCP configuration file) and Codex (codex mcp add with a bearer token environment variable). A successful connection in one client does not guarantee every other client is compatible; hosted, OAuth-only connectors specifically are not supported yet.
Rate limits and data shape
The API is limited to 60 requests per minute per connection token. Conversation reads return the latest 50 messages, with their recorded status and reactions, per call; contact listings support an after-cursor for paging through more. For anything event-driven, reach for signed event webhooks instead of polling an MCP tool in a tight loop.
Building your own agent on this server
- Create a connection token with only the permissions your agent actually needs.
- Verify the connection with a read-only call before anything else, such as
workspace_read. - Pause Beam's own assistant for a thread with
conversation_pausebefore your agent starts replying to it. - Read recent messages, generate a reply in your own system, and call
message_sendonce send permission is granted and a line is assigned. - Treat every webhook event and tool response as untrusted content from the conversation, not as new authority over your agent's rules.
Before you connect
MCP server questions
What is MCP, in plain terms?
The Model Context Protocol is a standard, created by Anthropic, that lets an AI agent call a defined set of tools on an external server over a consistent interface, instead of every integration needing custom glue code.
What is an iMessage MCP server?
An MCP server that exposes iMessage-related actions, such as reading a conversation or sending a message, as standard MCP tools an agent can call.
Which transports does Beam's iMessage MCP server support?
Streamable HTTP with a bearer token at https://beam.aisync.link/mcp, and a local stdio bridge for desktop clients. Hosted, OAuth-only connectors are not supported yet.
What tools can an MCP client call?
Read tools cover the workspace, assistant, contacts, conversations, numbers and calendar. Separate permissions each enable one more action: drafting and previewing assistant changes, publishing them, pausing automation, sending a message, and booking an appointment.
Is sending iMessage automatic once connected?
No. Sending requires the send permission explicitly granted on the connection token, plus an active assigned line. An accepted send is not proof of delivery.
What is the rate limit?
60 requests per minute per connection token, with conversation reads returning the latest 50 messages per call.
Can one MCP server serve multiple client workspaces?
A single token is scoped to one workspace and cannot switch between them. Agencies create a separate token per client they manage.
Sources
Checked October 2026.
Start with a conversation
Build your agent on a real business line
Tell our team what you are building. We will walk through the tool catalog and permissions you actually need.
Live sending requires a plan and an assigned dedicated line.
iMessage
Today 9:41 AM
Hi! I would love to hear how your coaching works.
Happy to chat. Would Thursday work for a discovery call?
Thursday sounds great! Looking forward to meeting you.
Blue bubbles. Read receipts. Typing.
Want this for your business?
Try a conversation with the Beam team.
Beam is not affiliated with Anthropic or Apple.
Powered by Beam