MCP Server

What MCP is

The Model Context Protocol is an open standard for connecting AI assistants to outside systems. An MCP server publishes a set of tools, each with a name, a description, and a typed input schema. The assistant reads that list, picks the tool that fits the request, and calls it. The BlueReacher MCP server wraps the BlueReacher API so an assistant can operate your outbound messaging directly: check which numbers are reachable on iMessage, send from your dedicated lines, manage contacts and opt-outs, and pull campaign results. Your lines are managed for you, and no A2P registration is required.

Install

The server ships as an npm package and runs over stdio. It needs Node 18 or later.

Claude Code

claude mcp add bluereacher \
  --env BLUEREACHER_API_KEY=bluereacher_your_api_key \
  -- npx -y @bluereacher/mcp

Confirm it connected:

claude mcp list

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "bluereacher": {
      "command": "npx",
      "args": ["-y", "@bluereacher/mcp"],
      "env": {
        "BLUEREACHER_API_KEY": "bluereacher_your_api_key"
      }
    }
  }
}

Cursor

Add this to .cursor/mcp.json in your project, or to the global config at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bluereacher": {
      "command": "npx",
      "args": ["-y", "@bluereacher/mcp"],
      "env": {
        "BLUEREACHER_API_KEY": "bluereacher_your_api_key"
      }
    }
  }
}

Windsurf

Add the same block to ~/.codeium/windsurf/mcp_config.json.

VS Code

With GitHub Copilot’s agent mode, add to .vscode/mcp.json:

{
  "servers": {
    "bluereacher": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bluereacher/mcp"],
      "env": {
        "BLUEREACHER_API_KEY": "bluereacher_your_api_key"
      }
    }
  }
}

Restart the client after saving. Tools appear under a bluereacher group.

Authentication

The server reads one environment variable, BLUEREACHER_API_KEY. Every call it makes carries that key as a bearer token against the API:

Authorization: Bearer bluereacher_your_api_key
Content-Type: application/json

Keys are generated per customer in your dashboard under Settings, then API Keys. Anyone holding a key can send from your lines, so keep it in the client’s env config rather than in a file you commit. Revoking a key in the dashboard takes effect immediately.

Tool reference

Messaging

Tool	What it does
`bluereacher_send_message`	Send an iMessage to one recipient, with automatic RCS then SMS fallback. Params: `to`, `content`, optional `media_url`, `line_id`, `external_id`, `scheduled_at`.
`bluereacher_send_group_message`	Send to an existing group thread by `group_id`, or create one from a `participants` array.
`bluereacher_get_message`	Retrieve one message with its full lifecycle detail: status, timestamps, channel used, failure reason if any.
`bluereacher_get_message_status`	Lightweight delivery-status poll for a single message id.
`bluereacher_list_messages`	List and filter history by status, channel, direction, contact, line, or date range, with cursor pagination.
`bluereacher_cancel_messages`	Cancel queued or scheduled sends for a contact before they go out.

Availability and contacts

Tool	What it does
`bluereacher_check_imessage`	Check whether one address can receive iMessage. Returns `imessage` and `rcs` booleans. The recipient is never notified.
`bluereacher_check_imessage_bulk`	Batch availability check, up to 100 addresses per call.
`bluereacher_create_contact`	Create a contact with `phone`, `email`, name fields, `tags`, and `custom_fields`.
`bluereacher_get_contact`	Retrieve a contact by id or phone number.
`bluereacher_list_contacts`	Search and filter contacts by query, tag, or opt-out state.
`bluereacher_update_contact`	Update fields, tags, or custom data on an existing contact.
`bluereacher_set_opt_out`	Add a contact to your do-not-contact list. Enforced immediately across every line on the account.

Lines

Tool	What it does
`bluereacher_list_lines`	List your dedicated iMessage lines with status, daily capacity, and messages sent today.
`bluereacher_get_line`	Retrieve one line with its health indicator and remaining capacity.

Rich messaging

Tool	What it does
`bluereacher_send_typing_indicator`	Show the typing bubble in a one-to-one thread.
`bluereacher_mark_read`	Send a read receipt for a conversation.
`bluereacher_send_reaction`	Send or remove a tapback: love, like, dislike, laugh, emphasize, question.
`bluereacher_send_voice_note`	Send an audio file that renders as a native inline voice memo.
`bluereacher_upload_media`	Upload a file and get a reusable hosted URL for use across sends.

Campaigns and reporting

Tool	What it does
`bluereacher_create_campaign`	Create a multi-step sequence with per-step content, delays, and stop conditions.
`bluereacher_add_contact_to_campaign`	Enroll a contact into an existing campaign.
`bluereacher_get_campaign_stats`	Pull sent, delivered, replied, reply rate, and opt-out counts for a campaign.
`bluereacher_list_webhooks`	List registered webhook endpoints with delivery health.

Example workflows

These are the requests operators actually type. Each one chains several tools without you naming them. Qualify a list before spending sends

Check which of these 40 numbers can receive iMessage, then tell me the percentage and list the ones that can’t.

The assistant calls bluereacher_check_imessage_bulk, groups the results, and reports back. Nothing is sent. Follow up on a stalled thread

Find everyone I messaged more than five days ago who never replied, and draft a follow-up for each one.

The assistant calls bluereacher_list_messages with a date filter, cross-references replies, and drafts. You approve before anything sends. Check line health before a push

How much capacity is left on my lines today?

One bluereacher_list_lines call, summarized. Read the result of a campaign

How did the Q3 reactivation campaign do, and who replied positively?

Chains bluereacher_get_campaign_stats and bluereacher_list_messages filtered to inbound.

Safety and scoping

An assistant that can send messages to real people deserves more care than one that can read files. Keep sending human-approved. The most reliable pattern is: let the assistant research, segment, and draft freely, then have a person approve the send. Availability checks, list analysis, and reporting are safe to automate. Bulk sending is not, and this is a product decision rather than a technical limit. Use a scoped key. Generate a separate API key for assistant use so you can revoke it without disrupting your production integration. Consent rules do not change. TCPA applies to every message regardless of what generated it, and opt-outs are enforced platform-wide, so a contact who has opted out cannot be messaged by an assistant either. See the compliance guide for the full picture. Pacing still matters. An assistant that can send 500 messages in a minute will happily do so. Sending capacity exists to protect your line reputation. See rate limits.

Troubleshooting

Tools do not appear. Restart the client fully. Confirm Node 18 or later with node --version. In Claude Code, run claude mcp list to see the connection state. 401 errors on every call. The key is missing, malformed, or revoked. Confirm the env var name is exactly BLUEREACHER_API_KEY and the value starts with bluereacher_. A send fails with contact_opted_out. Working as intended. That contact opted out and cannot be messaged from any line on your account. A send fails with capacity_exceeded. The line hit its daily conversation capacity. Add a line rather than pushing the existing one harder.

Next steps

Quickstart covers the same operations over plain HTTP.
Webhooks covers receiving replies in your own systems.
Deliverability covers keeping lines healthy at volume.

Getting started

Integrations

Platform

What MCP is

Install

Claude Code

Claude Desktop

Cursor

Windsurf

VS Code

Authentication

Tool reference

Messaging

Availability and contacts

Lines

Rich messaging

Campaigns and reporting

Example workflows

Safety and scoping

Troubleshooting

Next steps

​What MCP is

​Install

​Claude Code

​Claude Desktop

​Cursor

​Windsurf

​VS Code

​Authentication

​Tool reference

​Messaging

​Availability and contacts

​Lines

​Rich messaging

​Campaigns and reporting

​Example workflows

​Safety and scoping

​Troubleshooting

​Next steps

What MCP is

Install

Claude Code

Claude Desktop

Cursor

Windsurf

VS Code

Authentication

Tool reference

Messaging

Availability and contacts

Lines

Rich messaging

Campaigns and reporting

Example workflows

Safety and scoping

Troubleshooting

Next steps