# MCP server > Connect Claude, ChatGPT, Cursor, VS Code or any MCP client to BlueBot, and your assistant can read your conversations, check your Mac and text people from your own number when you ask. 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](https://modelcontextprotocol.io) (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 | Job | Tools | | ------ | ------------------------------------------------------------------------ | | Read | `list_conversations`, `get_conversation`, `list_messages`, `get_message` | | Send | `send_text`, `schedule_text`, `cancel_text`, `send_template` | | People | `search_contacts`, `create_contact`, `enroll_in_sequence` | | Check | `get_device_status`, `lookup_service`, `list_templates`, `get_analytics` | [MCP tools](https://usebluebot.com/docs/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](https://usebluebot.com/docs/concepts/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](https://usebluebot.com/docs/mcp/auth) 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). ```bash 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. ```text 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](cursor://anysphere.cursor-deeplink/mcp/install?name=bluebot&config=eyJ1cmwiOiJodHRwczovL3VzZWJsdWVib3QuY29tL21jcCJ9) ```json title="~/.cursor/mcp.json" { "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](vscode:mcp/install?%7B%22name%22%3A%22bluebot%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fusebluebot.com%2Fmcp%22%7D) ```json title=".vscode/mcp.json" { "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. ```json title="~/.codeium/windsurf/mcp_config.json" { "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. ```text 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. ```json title="claude_desktop_config.json" { "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. | You got | It means | Do next | | ------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | An answer about your Mac, its checks and today's counts | The assistant is connected and signed in. | Try [a prompt or two](https://usebluebot.com/docs/mcp/prompts). | | The client says it can't find any tools from BlueBot | It hasn't connected, or it read the tool list before you signed in. | Reconnect from the client's MCP settings. In Claude Code, run `/mcp`. | | `401` or "unauthorized" | The key is wrong or revoked, or the sign-in expired. | Paste the key again, or sign in again from the client. | | A tool answers that the key lacks a scope | The key can't do what the tool needs, such as sending with a read-only key. | That's the key working as meant. Use a key with that scope if you want the tool. [API keys and scopes](https://usebluebot.com/docs/concepts/api-keys) | ## 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. > **What the assistant reads goes to its provider.** When a tool reads a conversation, those texts go to the company that runs your assistant (Anthropic for Claude, OpenAI for ChatGPT, and so on) under its terms, like anything else you share in the chat. Connect only assistants you'd trust with your texts. ## 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: ```json title="send_text, held by quiet hours" { "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](https://usebluebot.com/docs/concepts/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 - [MCP tools](https://usebluebot.com/docs/mcp/tools): Every tool, its inputs and the scope it needs. - [OAuth or an API key](https://usebluebot.com/docs/mcp/auth): How each sign-in works, and how to revoke it. - [Example prompts](https://usebluebot.com/docs/mcp/prompts): What to ask, and what the assistant does. - [Docs for AI agents](https://usebluebot.com/docs/for-ai-agents): Point a coding agent at these docs to build an integration.