MCP server

BlueBot runs an MCP server, so an AI assistant can use your texts the way you would. Ask Claude "Who's waiting on a reply from me?" and it reads your conversations. Ask it to "text Ana that I'm running ten minutes late" and it sends the text from your number, through your Mac, like any other. MCP (the Model Context Protocol) is the open standard most assistants use to call outside tools.

For example, Jordan, a real estate agent, opens Claude Desktop before the first showing and asks, "Anything from buyers overnight?" Claude reads the conversations that wait on Jordan, sums up three replies, and drafts an answer to the one asking about parking. Jordan reads the draft, says "send it", approves the tool call, and the text goes from Jordan's own number.

What your assistant can do

MCP tools describes each one with its inputs and the scope it needs.

What it never does

• Skip your sending rules. A text an assistant sends goes through the same checks as one from the API: your pace, quiet hours, the new-people limit, the daily ceiling and your stop list. A text that can't go yet is held with a reason, and the assistant tells you why. Holds
• Text anybody on your stop list, or anybody at all when your Mac is offline: the text waits for the Mac instead.
• Change your account. There are no tools for settings, API keys, webhooks, billing or deleting anything.
• See secrets. API keys and webhook signing secrets never pass through the server.
• Do what Messages can't. It can't start a new group chat, send a tapback or edit a sent text.

Every text an assistant sends has source: "mcp", so it's easy to find in Messages in the dashboard and in the API.

Connect your assistant

The server is one address, and you can sign in to it two ways:

• OAuth: the assistant opens a BlueBot page where you sign in and approve it. There's no key to copy, and you can disconnect it later from Developers → Connected apps. Claude Desktop, claude.ai, ChatGPT and VS Code use this.
• An API key in an Authorization: Bearer header. Use it for a client that can't do OAuth, or when you want to limit the assistant to a key's scopes, such as a read-only key.

OAuth or an API key compares them. Then follow the steps for your client:

The server's address is https://usebluebot.com/mcp. Every client below connects to that one address.

Claude Code

Add it once from a terminal. Without --header, Claude Code signs in with OAuth the first time you use a tool (run /mcp to start).

claude mcp add --transport http bluebot https://usebluebot.com/mcp \
  --header "Authorization: Bearer $BLUEBOT_API_KEY"

Claude Desktop

Settings → Connectors → Add custom connector. Name it BlueBot, paste the URL, and sign in to BlueBot when asked; no key to paste. The same connector works on claude.ai.

https://usebluebot.com/mcp

Cursor

Use the button, or add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project) and set BLUEBOT_API_KEY in your environment.

Add to Cursor

{
  "mcpServers": {
    "bluebot": {
      "url": "https://usebluebot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BLUEBOT_API_KEY}"
      }
    }
  }
}

VS Code

Use the button, or add this to .vscode/mcp.json. VS Code signs in with OAuth; to use a key instead, add an Authorization header.

Add to VS Code

{
  "servers": {
    "bluebot": {
      "type": "http",
      "url": "https://usebluebot.com/mcp"
    }
  }
}

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers in Cascade.

{
  "mcpServers": {
    "bluebot": {
      "serverUrl": "https://usebluebot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BLUEBOT_API_KEY}"
      }
    }
  }
}

ChatGPT

Settings → Apps and connectors → Advanced → turn on Developer mode, then Create: name it BlueBot, paste the URL, choose OAuth, and sign in to BlueBot.

https://usebluebot.com/mcp

Any client (mcp-remote)

For a client that only starts local servers, mcp-remote bridges to BlueBot over HTTP. This is Claude Desktop’s claude_desktop_config.json shape; most clients take the same.

{
  "mcpServers": {
    "bluebot": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://usebluebot.com/mcp",
        "--header",
        "Authorization:${BLUEBOT_AUTH}"
      ],
      "env": {
        "BLUEBOT_AUTH": "Bearer bb_live_…"
      }
    }
  }
}

Check it works

Ask your assistant: "Is my Mac online?" It calls get_device_status and answers from what BlueBot knows.

Approve what your assistant sends

Your client decides whether to ask before it calls a tool. Most ask by default, and let you allow a tool once or always.

• Allow the read tools always if you like: list_conversations, get_conversation, get_device_status and the rest only read.
• Keep asking for the send tools: send_text, schedule_text, send_template and enroll_in_sequence text real people from your number. Read the words and the number before you approve.
• For read-only use, connect with a read-only key. A key with only messages:read, contacts:read and account:read can't send whatever the assistant decides, because BlueBot refuses the send tools for it.
• Undo is cancel. A scheduled or held text can be canceled until it goes: ask the assistant to cancel it, or cancel it in Messages. A text that was sent can't be taken back.

How answers look

Each tool answers with compact structured data for the assistant and a one-line summary for you. A send answers with the message and its state, like POST /v1/messages does. When a text can't go yet, it comes back queued with a hold, and the assistant explains it:

{
  "id": "msg_1Hq2LxW9cVbN3mKpRtYs0a",
  "state": "queued",
  "to": "+15555550123",
  "service_requested": "auto",
  "hold": {
    "reason": "quiet_hours",
    "until": "2026-11-14T13:00:00.000Z",
    "description": "Waiting for quiet hours to end at 8:00 AM."
  },
  "source": "mcp"
}

That text isn't lost: it goes at 8:00 the next morning in your time zone, when quiet hours end. Quiet hours

For MCP client developers

• Transport: Streamable HTTP at https://usebluebot.com/mcp.
• API keys: Authorization: Bearer bb_live_…, the same keys as the REST API, with the same scopes.
• OAuth 2.1: an unauthenticated request gets 401 with a WWW-Authenticate header pointing at https://usebluebot.com/.well-known/oauth-protected-resource. The authorization server's metadata is at https://usebluebot.com/.well-known/oauth-authorization-server. Clients register themselves at /oauth/register (dynamic client registration) and use the authorization code flow with PKCE (S256 only).
• Server card: https://usebluebot.com/.well-known/mcp.json describes the server.
• Tools: every tool calls the same code as the REST API, so the API reference's rules (states, holds, errors) hold for MCP too.

Next