Bolna MCP Server

Remote MCP server (Streamable HTTP) wrapping the Bolna voice AI REST API (https://api.bolna.ai): 116 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.

Two endpoints

The directory surface is a fixed subset. A directory listing is reviewed as a whole, so every tool on it is surface area to justify. /api/connector/mcp serves the nine tools named in src/tools/directory-surface.ts and nothing else, while /api/mcp keeps growing. Adding a name to that list means adding it to what Anthropic reviews, so do it deliberately. Both routes are built by the same factory in src/lib/mcp-route.ts and share the same tool implementations.

The restriction is applied at registration time, not per call: tools off the list never enter the server’s registry, so they are absent from tools/list and un-callable by name. Prompts are dropped the same way, so the connector answers prompts/list with “method not found” rather than advertising the four on /api/mcp.

Two things also differ on the connector, and only there:

• No api_key parameter. Every tool on /api/mcp accepts an optional api_key to target another account for one call (see above). It is stripped from both the schema and the incoming arguments on the connector, so it always acts as the OAuth-authenticated user. The strip lives in the same wrapper as the allowlist — no tool implementation is touched.
• Its own server instructions. SERVER_INSTRUCTIONS describes tools and prompts the connector doesn’t register, so it sends CONNECTOR_INSTRUCTIONS from src/tools/prompts.ts instead.

OAuth is per-surface. RFC 9728 metadata must declare a resource equal to the URL the client connected to, and Claude rejects a mismatch, so a single hardcoded document can’t serve two paths. /api/connector/mcp points at the path-insertion form /.well-known/oauth-protected-resource/api/connector/mcp, served by a catch-all route that answers only for known transport paths. /api/mcp keeps the bare /.well-known/oauth-protected-resource it has always handed out, so already-connected clients are unaffected. Both documents name the same Supabase authorization server, and verifyToken does no audience check of its own — the token is forwarded to api.bolna.ai either way — so the sign-in flow at the two URLs is identical.

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.

Available tools

116 tools across 17 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)

Extraction categories

Phone numbers & inbound

SIP trunks (bring your own carrier)

Legacy SIP trunks (deprecated)

Kept for trunks that already exist on the legacy plane; new setups use the SIP trunk tools above.

Sub-accounts (enterprise)

Voice & providers

Knowledgebase (RAG)

Violations

Workflows

Multi-step, per-contact automations (call an agent, branch on the outcome, wait, call an API, wait for a callback from your own system, message over WhatsApp, retry, and so on) — distinct from a single agent’s own conversation. A workflow is edited as a draft, then published as an immutable version before it can run.

Workflow campaigns

Runs many contacts through one workflow version as a batch.

Workflow executions

A single contact’s run through a workflow, created by run_workflow or a campaign.

Graph agents

Node-based voice flows (llm_agent.agent_type: "graph_agent"). Create, edit, and validate the graph, and push events into live calls.

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 " \
  --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 "
      }
    }
  }
}

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 "
      ]
    }
  }
}

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=""

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 "
      }
    }
  }
}

Windsurf

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

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

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 "
      }
    }
  }
}

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 116 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 

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 (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