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

# Bolna MCP server quickstart

> Set up the Bolna MCP server at mcp.bolna.ai through the Claude connector directory, or connect it to Claude Code, Cursor, Windsurf or any client.

> **[Using Claude? Add the Bolna connector](https://claude.ai/directory/bolna)**
>
> Bolna is listed in Claude's connector directory. Click **Connect**, sign in with your Bolna account, and it works in Claude on the web, desktop and mobile — no API key or config file

The connector covers agents and their calls: create, inspect, update and delete agents, read executions and batches, and check your account. It can't place calls or manage phone numbers, knowledge bases, dispositions, SIP trunks, sub-accounts or workflows. For all of that, connect the full server below.

## Connect the full server

Every client needs the same two things — there's nothing to install, the server is hosted at `mcp.bolna.ai`:

```
URL:     https://mcp.bolna.ai/api/mcp
Header:  Authorization: Bearer <your BOLNA_API_KEY>
```

**1. Get your API key**

Grab it from the [Bolna Dashboard → Developers → API Keys](https://platform.bolna.ai/developers). Keep it secret — anyone with the key can read your account data and place calls that spend your balance.

A [sub-account](https://www.bolna.ai/docs/api-reference/sub-accounts/overview) key (`sa-...`) works here too, exactly like a main account's `bn-...` key — connect with it directly, or switch per-call later with the `api_key` argument described in the [Tool List](https://www.bolna.ai/docs/mcp-tool-list.md#calling-tools-with-a-different-account).

**2. Add the MCP server**

**Claude Code**

```bash theme={"system"}
claude mcp add --transport http bolna https://mcp.bolna.ai/api/mcp \
  --header "Authorization: Bearer <your BOLNA_API_KEY>" \
  --scope user
```

**Claude Desktop**

Desktop only launches local (stdio) servers, so reaching this remote HTTP server needs the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. Add to `claude_desktop_config.json`:

```json theme={"system"}
{
  "mcpServers": {
    "bolna": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.bolna.ai/api/mcp",
        "--header", "Authorization: Bearer <your BOLNA_API_KEY>"
      ]
    }
  }
}
```

Restart Claude Desktop after saving.

**Cursor**

Add to `.cursor/mcp.json`:

```json theme={"system"}
{
  "mcpServers": {
    "bolna": {
      "url": "https://mcp.bolna.ai/api/mcp",
      "headers": { "Authorization": "Bearer <your BOLNA_API_KEY>" }
    }
  }
}
```

**Windsurf**

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={"system"}
{
  "mcpServers": {
    "bolna": {
      "serverUrl": "https://mcp.bolna.ai/api/mcp",
      "headers": { "Authorization": "Bearer <your BOLNA_API_KEY>" }
    }
  }
}
```

**Codex CLI**

Reads the key from an environment variable:

```bash theme={"system"}
export BOLNA_API_KEY="<your BOLNA_API_KEY>"

codex mcp add bolna \
  --url https://mcp.bolna.ai/api/mcp \
  --bearer-token-env-var BOLNA_API_KEY
```

**Zed**

Add to `settings.json`. Zed doesn't support environment-variable interpolation in headers yet, so the key goes in directly:

```json theme={"system"}
{
  "context_servers": {
    "bolna": {
      "url": "https://mcp.bolna.ai/api/mcp",
      "headers": { "Authorization": "Bearer <your BOLNA_API_KEY>" }
    }
  }
}
```

**Any other client**

Point it at the URL and header above. If it only launches local (stdio) servers, bridge it with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```bash theme={"system"}
npx -y mcp-remote https://mcp.bolna.ai/api/mcp \
  --header "Authorization: Bearer <your BOLNA_API_KEY>"
```

**3. Verify the connection**

Start a new conversation and ask:

```
List my Bolna agents
```

A real list back means you're connected.

## Troubleshooting

> **Tools return an auth error**
>
> Check the header reads exactly `Authorization: Bearer <key>` — a missing space after `Bearer`, or quotes baked in from copy-paste, will break it. An invalid key surfaces as a `403` from the underlying Bolna API.

> **Client can't reach a remote HTTP server**
>
> Some clients (Claude Desktop is the common one) only support locally-run stdio servers — use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge shown above.

> **Not sure the server is even reachable**
>
> Test it directly with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
>
> ```bash theme={"system"}
> npx @modelcontextprotocol/inspector
> ```
>
> Connect with transport **Streamable HTTP**, URL `https://mcp.bolna.ai/api/mcp`, header `Authorization: Bearer <your BOLNA_API_KEY>`, and check all 115 tools appear under "List Tools".

> **[Tool list](https://www.bolna.ai/docs/mcp-tool-list.md)**
>
> Every tool the server exposes

> **[Prompt cheatsheet](https://www.bolna.ai/docs/mcp-prompts.md)**
>
> Copy-paste prompts for common tasks


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