Handling Beam's MCP Rate Limit in a Custom Claude Agent

This is for the case where you are writing application code against Claude's API yourself, not using Claude Desktop, Claude Code, or the custom connector dialog inside claude.ai. Those three clients already have documented, built-in paths to Beam, covered separately in our guides to the Claude Desktop stdio bridge, Claude Code's MCP registration command, and the bearer-token custom connector. None of those apply once you are writing the agent loop yourself and deciding how your own backend talks to Beam, which is the gap this guide fills, verified against Beam's developer access reference and Anthropic's MCP connector documentation as of this writing.

Beam gives a developer exactly two documented ways into the same workspace, and both take the identical Bearer token. The REST layer is a set of plain HTTP endpoints, POST /v1/messages to send, GET /v1/messages/:id to check status, DELETE /v1/messages/:id to cancel a queued send, and similar routes for contacts, numbers, and conversation history. Your application code calls these directly with an ordinary HTTP client, the same way it would call any other REST API, and reads back ordinary JSON.

The MCP catalog is a second surface on the same workspace, not a separate product. GET /v2/tools returns the tools and argument schemas your token can call, and POST /v2/tools executes one of them, using the same Bearer token as the MCP endpoint at https://beam.aisync.link/mcp itself, per our iMessage MCP server guide. The tool names map closely to the REST actions, message_send does roughly what POST /v1/messages does, so what differs is the calling convention, not the destination. If your backend decides when to send, in response to a webhook, a cron job, or a queue message, you are writing REST calls whether or not you dress them up as MCP tools. If Claude itself is reasoning about whether to text someone right now mid-conversation, MCP tool calls are the natural fit, since that is what gives the model a schema it can reason over.

For a programmatic sender, meaning your backend decides when to text someone rather than Claude deciding mid-conversation, calling REST directly is the simpler path, and the rate limit does not change that answer, since it applies identically either way. The real reasons to prefer REST here are operational: you control retries, timeouts, and logging with your own HTTP client, instead of paying for a tool-schema round trip just to make a call your own code already knows it needs to make.

MCP earns its place when Claude itself decides whether and when to act, a genuinely different job from a backend firing a send on a schedule. If your agent reads a customer's incoming message and reasons about whether to reply, escalate, or wait, giving it message_send and conversation_read as tools through MCP lets it make that call directly rather than your code pre-encoding every branch of that judgment.

Anthropic's own MCP connector, the server-side feature letting Claude call a remote MCP server without you running a client loop yourself, is a real third option if you lean toward MCP. It requires declaring the server with mcp_servers and adding a matching mcp_toolset entry under tools, under a current beta header, or the request is rejected outright (platform.claude.com: MCP connector). That still sends the same request to Beam's endpoint under the hood, so it inherits the 60-per-minute ceiling exactly like a client you host yourself; choosing it is a question of who manages the connection, not a way around the limit.

Treat 60 requests a minute as a budget to spend deliberately, not a wall to slam into and bounce off of. Default to event webhooks and reserve polling for the rare case where you genuinely need a live answer right now, since a webhook push on message.received costs nothing against the ceiling, as Beam is the one calling your endpoint instead of you calling Beam's. Where a tool already returns more than you asked for, use that instead of asking again: conversation_read already returns the latest 50 messages in one call, so reading history message by message wastes requests on something a single call already covers. Give each workload its own token rather than sharing one across everything the agent does, since the limit is scoped per token, and a nightly batch job sharing a token with a live conversational agent can starve each other during a burst.

On the retry side, back off on a real schedule rather than a tight retry: a failed call should wait progressively longer before the next attempt, not fire again immediately. And never retry a write by minting a new idempotency key just to dodge a throttling error. Every write needs a unique request_key, and reusing that same key returns the stored result instead of repeating the action, so a fresh key on retry risks sending the same text twice.

Here is the shape of a simple limiter wrapping a direct REST call, written to keep the request rate under the ceiling instead of discovering it the hard way:

const BASE_URL = "https://beam.aisync.link";
const MAX_PER_MINUTE = 60;
const WINDOW_MS = 60_000;
let timestamps: number[] = [];

async function callBeam(path: string, init: RequestInit) {
  const now = Date.now();
  timestamps = timestamps.filter((t) => now - t < WINDOW_MS);
  if (timestamps.length >= MAX_PER_MINUTE) {
    const waitMs = WINDOW_MS - (now - timestamps[0]);
    await new Promise((r) => setTimeout(r, waitMs));
  }
  timestamps.push(Date.now());
  const res = await fetch(BASE_URL + path, init);
  if (res.status === 429 || res.status >= 500) {
    await new Promise((r) => setTimeout(r, 2000));
    return callBeam(path, init);
  }
  return res;
}

This is deliberately plain: a sliding window in memory, a wait before any call that would exceed it, one retry with a short pause on a throttling or server error. A production agent will want that window shared across processes rather than held in one array.