## MCP server & skill

Working with an AI assistant? Connect it here first — this is the fastest way to send a message, and there is no API key to paste.

The Project Blue MCP server gives Claude Desktop, Claude Code, Cursor, and any other MCP-compatible client the ability to send iMessage and SMS, place FaceTime Audio calls, manage contacts, run Workflows, and read message and call history — directly from the editor or chat surface. Authentication is OAuth 2.1 in the browser.

Writing code against the REST API instead? Start with the [Quickstart](https://api.tryprojectblue.com/#quickstart).

### Server URL

### Two ways to connect

**Add the server directly.** This is the standard path and works in any MCP client — paste the URL, or run the one-liner in the rail. Nothing else is installed.

**Or install the plugin** (Claude Code only). It registers the same server and adds a Project Blue skill carrying the workflow rules the tool descriptions cannot: the trial verification sequence, when a retry is being deduplicated rather than failing, the FaceTime call lifecycle, and which contact endpoint merges versus replaces.

> **Neither path supersedes the other**
>
> Both connect to the same server with the same tools and the same OAuth flow. `claude plugin install` is a convenience, not a requirement — if you already added the server with `claude mcp add`, it keeps working and there is nothing to migrate. Installing both would simply register the server twice, so pick one.

### Set up your client

Pick your client in the rail and run the snippet. Every one of them ends the same way: your client opens a browser to **app.tryprojectblue.com**, you approve the connection, and it is done. OAuth 2.1 with dynamic client registration — no key to paste, no tokens to rotate.

| Client | Where it goes |
| --- | --- |
| Claude Code | `claude mcp add`, or install the plugin below |
| Codex | `codex mcp add` then `codex mcp login`, or `~/.codex/config.toml` |
| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` |
| Claude Desktop | Settings → Connectors → Add custom connector, then paste the server URL |

Any other client that speaks remote MCP over streamable HTTP works with the server URL alone. For one that only accepts stdio servers, use `mcp-remote` as an adapter — both are in the rail.

### Available tools

| Tool | Type | Description |
| --- | --- | --- |
| `send_message` | write | Send an iMessage or SMS to a single recipient. Supports media, audio, AI voice memo, and an optional lineId override. |
| `send_group_message` | write | Send an iMessage or SMS to a group of 2–32 recipients. Queued (status always queued, service always null). Same numbers reuse the thread. No CRM sync. Unavailable on trial accounts — see Trial Accounts. |
| `lookup_imessage_availability` | read | Check whether a phone number supports iMessage. |
| `get_lines` | read | List the user's Project Blue sending lines (lineId, devicePhoneNumber, customName). |
| `list_messages` | read | List recent inbound/outbound messages with filters (service, direction, line, date ranges). |
| `get_message` | read | Fetch a single message by its opaque message_handle. |
| `get_call_logs` | read | List the user's outbound dialer call logs with filters for line and answered_at range. Includes call status, disposition, transcript, and recording URL when available. |
| `start_facetime_call` | write | Place a FaceTime Audio call from a FaceTime-enabled line. Returns call_uuid plus Agora WebRTC credentials the caller must use to join the call audio. Requires FaceTime Audio on the account. |
| `get_facetime_call_status` | read | Poll a FaceTime call's live status (initiated, ringing, answered, ended, declined, no_answer, failed) by call_uuid. |
| `end_facetime_call` | write | Hang up an in-progress FaceTime call by call_uuid. |
| `create_external_contact` | write | Create (or upsert by phone number) an external contact with name, email, and custom JSON metadata. For accounts without a connected CRM. |
| `get_external_contacts` | read | List the user's external contacts (newest first) with pagination, or look one up by phone number. |
| `update_external_contact` | write | Update an external contact's name, email, note, or customFields by contact id. customFields is replaced wholesale, not merged. |
| `list_flows` | read | List the user's published Workflows (id and name). Use the id as flowId with enroll_contact_in_flow. |
| `enroll_contact_in_flow` | write | Enroll a contact in a published Workflow. Starts the run immediately and may send real messages. Returns runId and the pinned pb_line_id. |
| `cancel_flow_runs` | write | Cancel all active Workflow runs for a contact. Safe when the contact has no active runs. |

**Connect — Claude Code**

Opens a browser to complete OAuth on first use.

```bash
claude mcp add --transport http project-blue \
  https://api.tryprojectblue.com/api/mcp
```

**Connect — Codex**

Add the server, then authenticate. Codex picks HTTP transport from --url.

```bash
codex mcp add project-blue \
  --url https://api.tryprojectblue.com/api/mcp

codex mcp login project-blue
```

**Connect — Cursor**

~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

```json
{
  "mcpServers": {
    "project-blue": {
      "url": "https://api.tryprojectblue.com/api/mcp"
    }
  }
}
```

**Connect — VS Code**

.vscode/mcp.json in the workspace.

```json
{
  "servers": {
    "project-blue": {
      "type": "http",
      "url": "https://api.tryprojectblue.com/api/mcp"
    }
  }
}
```

**Connect — Codex (TOML)**

~/.codex/config.toml, if you prefer editing config directly.

```toml
[mcp_servers.project-blue]
url = "https://api.tryprojectblue.com/api/mcp"
auth = "oauth"
```

**Connect — Any client**

Paste this URL into any MCP client's connector settings.

```
https://api.tryprojectblue.com/api/mcp
```

**Connect — mcp-remote**

Adapter for clients that only accept stdio servers.

```json
{
  "mcpServers": {
    "project-blue": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.tryprojectblue.com/api/mcp"]
    }
  }
}
```

**Plugin — Claude Code**

Optional: same server, plus the Project Blue skill.

```bash
claude plugin marketplace add try-pb/pb-api
claude plugin install project-blue@project-blue
```