> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluereacher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Cursor, Windsurf, or any MCP client to BlueReacher so an AI assistant can check iMessage availability, send messages, manage contacts, and read campaign results.

## 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

```bash theme={null}
claude mcp add bluereacher \
  --env BLUEREACHER_API_KEY=bluereacher_your_api_key \
  -- npx -y @bluereacher/mcp
```

Confirm it connected:

```bash theme={null}
claude mcp list
```

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](/platform/compliance) 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](/guides/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](/guides/quickstart) covers the same operations over plain HTTP.
* [Webhooks](/api-reference/webhooks) covers receiving replies in your own systems.
* [Deliverability](/platform/deliverability) covers keeping lines healthy at volume.