Connect an AI agent to Beep (MCP)

Beep hosts a remote MCP (Model Context Protocol) server, so any MCP-capable AI agent — Claude, Codex, ChatGPT in developer mode, or your own agent framework — can work your Beep workspace directly: triage the inbox, search and reply to messages, manage tags and workflows, and run campaigns.

The agent acts as you. Connecting uses OAuth: you sign in to Beep in your browser, review the scopes the agent is requesting, and consent. The agent can never do anything your own Beep role doesn't allow, and you can revoke the connection at any time.

Connecting

The MCP endpoint is:

https://mcp.beepmessaging.com/mcp

Add it to your client as a remote (streamable HTTP) MCP server. The server publishes standard OAuth discovery metadata, so compliant clients start the browser sign-in automatically the first time you use a tool. For example, in Claude Code:

claude mcp add --transport http beep https://mcp.beepmessaging.com/mcp

then authenticate the beep server when prompted (/mcp). Other clients follow the same shape: register the endpoint, complete the Beep sign-in and consent screen in the browser, and verify the server appears in the client's MCP list. The Beep dashboard's agent setup page has copy-paste instructions for popular clients.

Scopes

At consent time the connection is granted a set of scopes. A tool call fails with an authorization error if the connection lacks the tool's scope — and scope is only half the check: your workspace role is enforced on every call too, so an over-scoped token never grants more than your role allows.

Scope	Grants
`profile:read`	Read the connected user's profile.
`orgs:read`	List organizations you can access.
`workspaces:read`	List and load workspaces.
`inbox:read`	Read threads, search messages, list tags, workflows, saved responses and response groups.
`inbox:write`	Reply, send saved responses, assign, close/reopen threads; apply tags and workflows — singly or in bulk.
`campaigns:read`	List and load campaigns.
`campaigns:write`	Create campaign drafts.
`campaigns:launch`	Start campaigns (initiates real sending).
`admin:workspace`	Manage workspace configuration — tags, workflows, saved responses and response groups. Workspace Admin+.

Tool catalog

Identity & navigation (read)

Tool	What it does
`who_am_i`	Return the connected user and environment.
`list_organizations`	List accessible organizations.
`list_workspaces`	List accessible workspaces.
`get_workspace`	Load a specific workspace.
`list_organization_workspaces`	List the workspaces inside an organization.

Inbox

Tool	What it does
`list_inbox_threads`	List threads for a workspace with filters (status, assignee, tags, campaigns).
`search_messages`	Search messages; returns evidence-backed matches and can mint a search preview.
`get_thread`	Get a bounded page of messages; page 1 is latest and responses identify older pages.
`reply_to_thread`	Send a reply into a thread.
`assign_thread`	Assign a thread to a user.
`close_thread`	Close a thread.
`reopen_thread`	Reopen a thread.
`bulk_reply_to_threads`	Reply to up to 25 threads by explicit thread IDs.
`bulk_assign_threads`	Assign up to 100 threads.
`bulk_close_threads`	Close up to 100 threads.
`bulk_reopen_threads`	Reopen up to 100 threads.

Tool	What it does
`list_tags`	List workspace tags with pagination and name filtering (conversation and campaign scopes).
`create_tag`	Create a flat tag, a single-select tag group, or a new value in an existing group.
`apply_tags`	Apply conversation tags to one thread.
`remove_tags`	Remove conversation tags from one thread.
`bulk_tag_threads`	Apply or remove tags across up to 100 threads.

Workflows

Tool	What it does
`list_workflows`	List workflows (defaults to active manual workflows; flags reveal the rest).
`get_workflow`	Load a workflow and its ordered steps.
`apply_workflow`	Apply a workflow to one thread.
`create_workflow`	Create a workflow — a manual playbook or an automated trigger with ordered steps.
`update_workflow`	Update a workflow's metadata, active state, or trigger + steps together.
`bulk_apply_workflow`	Apply an active manual workflow to up to 100 threads.

Saved responses and response groups

Tool	What it does
`list_responses`	List saved responses; pass `thread_id` for the thread's campaign-scoped set, `include_all` for more.
`get_response`	Load a saved response with its groups and the campaigns that offer it.
`create_response`	Create a saved response, optionally filed into groups (Workspace Admin+).
`update_response`	Update a saved response; `group_ids` replaces its group membership (Workspace Admin+).
`delete_response`	Delete a saved response and report the running campaigns that lose it (Workspace Admin+).
`send_saved_response`	Send a saved response to a thread by reference, with usage attribution.
`bulk_send_saved_response`	Send a saved response to up to 25 threads or a search preview.
`list_response_groups`	List response groups with member and campaign counts.
`get_response_group`	Load a group with its members and attached campaigns.
`create_response_group`	Create a group, optionally with initial responses (Workspace Admin+).
`update_response_group`	Rename a group or add/remove responses — applies live to attached campaigns (Workspace Admin+).
`delete_response_group`	Delete a group (responses are kept) and report the running campaigns affected (Workspace Admin+).

See Use saved responses from your agent for the reply workflow.

Campaigns

Tool	What it does
`list_campaigns`	List workspace campaigns.
`get_campaign`	Load a campaign.
`create_campaign_draft`	Create a campaign draft from a list, with responses.
`start_campaign`	Start a campaign and enqueue its messages for sending.

Two tag namespaces. Thread filters accept both tag_ids (conversation tags — applied to the thread itself) and campaign_tag_ids (campaign tags — applied to the campaign the thread came from). They are separate namespaces; picking the wrong one silently returns the wrong threads.

Reading and replying to long threads

get_thread accepts an optional one-based page and page_size from 1 to 100. Page 1 contains the latest messages, and messages within every page are
returned in chronological order. The result includes:

{
  "items": [
    {
      "id": "50000000-0000-0000-0000-000000000003",
      "workspace_id": "10000000-0000-0000-0000-000000000001",
      "conversation_id": "40000000-0000-0000-0000-000000000001",
      "direction": "in",
      "body": "Can you help me with my order?",
      "from_number": "+15555550123",
      "to_number": "+15555550999",
      "status": "received",
      "created_at": "2026-07-29T12:03:00.000Z",
      "updated_at": "2026-07-29T12:03:00.000Z"
    }
  ],
  "page_info": {
    "page": 1,
    "page_size": 100,
    "has_older_messages": true,
    "next_page": 2
  }
}

Follow next_page until it is null when older context is needed. Do not
assume one call contains the full conversation.

Reply routing is independent of the page you most recently loaded.
reply_to_thread resolves the thread's actual newest inbound message before it
selects the recipient and sender, so a reply cannot be routed using stale
details from an older page.

A reply that is not part of a campaign is treated like a reply from the inbox:
reply_to_thread, bulk_reply_to_threads and the saved-response send tools
send immediately and are not held for the campaign's quiet hours. Campaign and
workflow sends still respect quiet hours, and opted-out recipients are never
sent.

MCP error results

Expected API failures are returned as MCP tool results with isError: true.
The human-readable content and machine-readable structuredContent describe
the same error:

{
  "status": 400,
  "request_id": "request-id",
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {}
  }
}

Use error.code for program logic, error.details to correct field- or
item-level input, and request_id when contacting support. Details are bounded
and may be omitted. Unexpected server, transport, or malformed upstream
failures are redacted to internal_error; clients never receive upstream
implementation details.

Risk levels: read, write, send

Tools fall into three tiers, and it's worth configuring your agent's approval policy around them:

Read tools (list_*, get_*, search_messages, who_am_i) have no side effects and are safe to auto-approve.
Write tools mutate workspace state — replies, assignments, tags, workflow authoring. Reversible, but visible to your team and (for replies) to recipients.
Send tools initiate real messaging at scale. start_campaign is the clearest case; bulk_reply_to_threads and bulk_apply_workflow with a sending workflow are bulk sending too, and their thread caps are deliberately lower (25). Treat these as requiring explicit human confirmation.

Idempotency keys

Every mutating tool that creates something or fans out across threads requires an idempotency_key (any string up to 255 characters — a UUID is a good choice). Retrying a call with the same key is safe: Beep detects the repeat and returns the original result instead of performing the action twice. Use a fresh key for each new intent, and reuse the key only to retry the same intent after a timeout or dropped connection.

Search previews

search_messages with create_preview: true returns a search_preview_id — an immutable snapshot of the matching thread set (default lifetime 30 minutes, extendable up to 24 hours with preview_ttl_seconds). Bulk tools always take explicit thread_ids; passing the search_preview_id alongside them constrains the call so it can only touch threads that were in the preview. This is the guardrail for "act on what we just found": the search results can't drift between the search and the bulk action, and a stale preview fails loudly rather than acting on the wrong threads.

Next steps

Manage tags and workflows from your agent — the authoring loop: find threads, tag and close them in bulk, and capture the treatment as a reusable workflow.