Bolna MCP Server

Remote MCP server (Streamable HTTP) wrapping the Bolna voice AI REST API (https://api.bolna.ai): 57 tools covering nearly every documented Bolna endpoint, TypeScript, deployed on Vercel via mcp-handler.

Live at mcp.bolna.ai — that page has the same connect instructions below with copy-paste buttons for each client.

MCP is an open protocol, not Claude-specific — this server works with any MCP-compatible client: Claude, Codex, Cursor, Windsurf, Zed, and others.

Endpoint corrections found while verifying tool paths against the live Bolna docs are documented in the comment block at the top of src/tools/index.ts.

Sub-accounts and switching between accounts

Sub-account API keys (format sa-...) work exactly like a main account's key (bn-...) — connect a separate client/connector with a sub-account's key as the Bearer token to work entirely within that sub-account.

To switch accounts within a single connected session instead of reconnecting, every tool also accepts an optional api_key argument that overrides the connection's own credential for just that call. Get a sub-account's key from list_sub_accounts' api_key field, then pass it to any tool call to run that call against that sub-account instead of the main account — e.g. "list agents in sub-account X" resolves to calling list_sub_accounts, finding X's key, then list_agents with that key passed as api_key.

Related MCP server: VoIPbin MCP Server

Available tools

57 tools across 14 categories. "Write" tools flagged Destructive modify, remove, or spend money and typically prompt for confirmation in MCP clients that respect tool annotations.

Agents & calls

Executions

Batches

Dispositions (structured call extraction)

Phone numbers & inbound

SIP trunks (bring your own telephony)

Sub-accounts (enterprise)

Voice & providers

Knowledgebase (RAG)

Violations

Account & documentation

Not exposed as a tool, all for the same reason — each needs either a raw file upload or a third-party secret as its request body, neither of which maps cleanly to a tool argument or belongs in a chat conversation:

• POST /providers (add a provider) — takes a third-party credential (e.g. a Twilio auth token)

• POST /knowledgebase with a PDF file (the URL variant is supported, above)

• POST /violations/submit — takes an evidence screenshot/document

Install & use

Prerequisite: your own Bolna API key (from the Bolna dashboard). Every client below needs the same two things: the server URL (https://mcp.bolna.ai/api/mcp) and that key as a Bearer token.

Claude Code

One command:

./scripts/connect.sh

or the equivalent by hand:

claude mcp add --transport http bolna https://mcp.bolna.ai/api/mcp \
  --header "Authorization: Bearer <your BOLNA_API_KEY>" \
  --scope user

or by hand-editing ~/.claude.json (or .mcp.json for a project-scoped copy):

{
  "mcpServers": {
    "bolna": {
      "type": "http",
      "url": "https://mcp.bolna.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer <your BOLNA_API_KEY>"
      }
    }
  }
}

Claude Desktop

Desktop's config only understands locally-run (stdio) servers, so reaching a remote HTTP server with a custom header needs the mcp-remote bridge, which runs locally and forwards the header on your behalf. Add this to claude_desktop_config.json:

{
  "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 editing the config.

Codex CLI

Reads the key from an environment variable rather than the config file:

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

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Windsurf

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

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

Zed

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

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

Claude Desktop (extension)

Instead of the mcp-remote bridge above, you can install this as a proper Desktop Extension (.mcpb) — a local, stdio-based build of the same 57 tools, packaged with a manifest so Claude Desktop can install it with one click and prompt you for your API key itself (no config file editing).

Build it from source:

npm run package:mcpb   # bundles src/stdio.ts, packs mcpb/ into bolna-mcp.mcpb

Then double-click bolna-mcp.mcpb, or drag it into Claude Desktop's Settings → Extensions, and enter your Bolna API key when prompted.

This local build talks directly to api.bolna.ai using only the raw API key path in src/lib/auth.ts — OAuth is specific to the remote server and isn't used here.

Any other MCP client

Point it at:

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

claude.ai web/mobile

This server now implements real OAuth (via Bolna's Supabase-backed authorization server), so claude.ai's own "Add custom connector" flow (Settings → Connectors) should work with just the URL — no manually pasted token needed, since claude.ai handles the login/consent redirect itself the same way Claude Code does. This hasn't been separately verified on claude.ai web/mobile specifically yet (only Claude Code's CLI flow has been tested end-to-end so far) — the CLI/config options above remain the proven paths in the meantime.

Try it

After connecting, start a new conversation and ask something like:

• "List my Bolna agents"

• "What's my Bolna wallet balance?"

• "Call +1... using my [agent name] agent"

Auth

Two ways to connect:

• OAuth — sign in through Bolna's own login (Supabase-backed). This is what claude.ai's custom-connector UI and Claude Code's Authenticate prompt use automatically; no manual token needed.

• Raw API key — pass your own Bolna API key as a Bearer token in the Authorization header, per the client examples above.

Either credential is verified before being forwarded to api.bolna.ai — see the comment block at the top of src/lib/auth.ts for how.

For local development, set BOLNA_API_KEY in .env and omit the header — the server falls back to it automatically.

Local dev

npm install
cp .env.example .env   # then fill in BOLNA_API_KEY
npm run dev             # or: vercel dev

The MCP endpoint is served at http://localhost:3000/api/mcp.

Deploy

Deployed under the Bolna AI Vercel team, aliased to mcp.bolna.ai:

vercel deploy --prod --scope bolna-ai

Set BOLNA_API_KEY as a Vercel environment variable only if you want a server-wide fallback for testing; production callers should supply their own key via the Authorization header.

Test with MCP Inspector

npx @modelcontextprotocol/inspector

In the Inspector UI, connect with:

• Transport: Streamable HTTP

• URL: http://localhost:3000/api/mcp (or your deployed URL + /api/mcp)

• Header: Authorization: Bearer <your Bolna API key> (optional locally if BOLNA_API_KEY is set in .env)

Then use the Inspector's "List Tools" and "Call Tool" panels to exercise each of the 13 core tools with valid and invalid input.

Privacy Policy

See mcp.bolna.ai/privacy.

License

MIT