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

# MCP Server

> Let Claude, Cursor or VS Code read and send your texts.

Connect it once, then ask in plain words:

* "Who's waiting on a reply from me?"
* "Sum up my conversation with Ava."
* "Text Ava that I'm running late."

> [!NOTE]
>
> Want your assistant to search these docs instead? Use the docs MCP server on [AI Coding Agents](https://docs.blujay.io/build-with-ai.md).

## Set up

* **Node.js 20** or later
* **Your API key** from the [API page](https://app.blujay.io/developer-tools) in Blujay, in place of `blu_your_api_key`

Your app starts the server with `npx`, so there's nothing to install.

> [!TIP]
>
> Using an assistant that runs on your computer, like Claude Code, Codex or Cursor? Tell it: "Set up the Blujay MCP server from docs.blujay.io/mcp-server", and paste your key when it asks.

### Claude Desktop

Open **Settings → Developer → Edit Config**, add this, then restart:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "blujay": {
      "command": "npx",
      "args": ["-y", "blujay-mcp"],
      "env": { "BLUJAY_API_KEY": "blu_your_api_key" }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add blujay \
  --env BLUJAY_API_KEY=blu_your_api_key \
  -- npx -y blujay-mcp
```

### Cursor

[Add to Cursor](https://cursor.com/en-US/install-mcp?name=blujay\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJsdWpheS1tY3AiXSwiZW52Ijp7IkJMVUpBWV9BUElfS0VZIjoiYmx1X3lvdXJfYXBpX2tleSJ9fQ==), or paste the Claude Desktop entry into **Cursor Settings → Tools & MCP → New MCP Server**.

### VS Code

[Install in VS Code](https://vscode.dev/redirect/mcp/install?name=blujay\&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22blujay-mcp%22%5D%2C%22env%22%3A%7B%22BLUJAY_API_KEY%22%3A%22blu_your_api_key%22%7D%7D), or add this to `.vscode/mcp.json`. It asks for your key once:

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "blujay": {
      "command": "npx",
      "args": ["-y", "blujay-mcp"],
      "env": { "BLUJAY_API_KEY": "${input:blujay-api-key}" }
    }
  },
  "inputs": [
    {
      "id": "blujay-api-key",
      "type": "promptString",
      "description": "Blujay API key",
      "password": true
    }
  ]
}
```

### Other apps

Run `npx -y blujay-mcp` with `BLUJAY_API_KEY` set. It uses stdio.

## Photos, effects and voice notes

| Ask | Sends |
| - | - |
| "Send Ava beach.jpg from my Desktop." | A photo, video or contact card: a file up to 100 MiB, or a link up to 10 MiB |
| "Send Ava the lease PDF." | A PDF or Office file, up to 100 MiB, over iMessage or RCS (not SMS) |
| "Wish Ava happy birthday with balloons." | An iMessage effect, in a chat that already exists |
| "Leave Ava a voice note." | An audio file or link, as a voice memo |

## Try it safely

Every text is real. While you try it out, add an option to `args`:

```json theme={null}
"args": ["-y", "blujay-mcp", "--allow-send-to", "+15555550123"]
```

| Option | What it does |
| - | - |
| `--allow-send-to` | Reaches only the numbers you list; no opt-outs or new webhooks |
| `--read-only` | Leaves out every tool that sends or changes anything |
| `--enable-invoke-api` | Adds `invoke_api`; reads only, with either option above |

Always on:

* **No double texts:** the same text to the same person within 10 minutes is held for your OK.
* **Texts aren't orders:** the assistant is told never to follow instructions in a message.
* **Only files you name:** media and documents, never keys or `.env`.
* **You approve each send** in most apps, unless you turned on auto-approve.

## Tools

### Reads

| Tool | What it does |
| - | - |
| `get_account` | Your workspace, numbers and what each can do |
| `list_conversations` | Recent conversations, by person or number |
| `get_conversation` | One conversation as a transcript |
| `find_unanswered` | Conversations waiting on your reply |
| `get_message` | A message's delivery status, and why it failed |
| `check_imessage` | Whether a number uses iMessage |
| `find_contacts` | List contacts, or find one by name, phone or email |
| `list_webhooks` | Webhooks and their recent deliveries |
| `search_docs` | Search these docs |

### Sends or changes

| Tool | What it does |
| - | - |
| `send_message` | Text a person or group, with a file, voice memo or effect |
| `react_to_message` | Add or remove a tapback |
| `edit_message` | Edit a sent iMessage |
| `unsend_message` | Unsend an iMessage |
| `mark_conversation_read` | Mark read; iMessage may show a receipt |
| `set_typing` | Show or hide the typing indicator |
| `update_group` | Rename a group, or add or remove someone |
| `save_contact` | Create or update a contact; a tag can start a workflow |
| `opt_out_contact` | Stop all texts to a contact |
| `create_webhook` | Create a webhook subscription |
| `invoke_api` | Any Blujay endpoint, only with `--enable-invoke-api` |

Ready-made prompts: **Who needs a reply?**, **Summarize a conversation**, **Send me a test message**.

## Troubleshooting

| Problem | Fix |
| - | - |
| "set BLUJAY\_API\_KEY" | Add the key to `env` in your app's MCP config, then restart the app |
| `401` or [`API_KEY_REVOKED`](https://docs.blujay.io/errors/api-key-revoked) | Email [support@blujay.io](mailto:support@blujay.io) for a new key |
| No tools show up | Run `npx -y blujay-mcp --version` in a terminal, then restart the app |

## Next steps

> [card] [AI Coding Agents](https://docs.blujay.io/build-with-ai.md)
>
> Let your assistant build on the API.

> [card] [SDKs](https://docs.blujay.io/sdks.md)
>
> TypeScript and Python libraries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.