# Bolna — how to use (mcp.ai)

Connect your Bolna account and use 35 tools for AI agents straight from your AI agent. Connect with your own API key. Create conversational voice agents using Bolna AI to enhance interactions, streamline operations and automate support.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_bolna?ms=1787291280000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `bolna_add_provider`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/bolna`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/bolna/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/bolna/add/provider` — Tool to add a new telephony or voice service provider to your Bolna account. Use when you need to configure API keys for providers like Twilio, Deepgram, or ElevenLabs before creating agents.
  - body: { user_id?: string, provider_name: string, is_api_request?: boolean, provider_value: string, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/copy/agent` — Tool to create a duplicate copy of an existing Bolna voice AI agent. Use when you need to replicate an agent's complete configuration (tasks, prompts, LLM settings, etc.) with a new name.
  - body: { user_id?: string, agent_id: string, agent_name: string, is_api_request?: boolean }
- `POST https://api.mcp.ai/api/bolna/create/agent` — Tool to create a new Bolna Voice AI agent using the v2 API. Use when you need to set up a new conversational agent from scratch with custom LLM, synthesizer, transcriber, and task configurations. This
  - body: { agent_config: object, agent_prompts: object }
- `POST https://api.mcp.ai/api/bolna/create/batch` — Tool to create a new outbound calling batch by uploading a CSV of contacts to obtain a batch_id. Use when initiating a batch campaign; follow by calling BOLNA_SCHEDULE_BATCH_BY_ID to schedule executio
  - body: { file: object, agent_id: string, from_phone_number?: string }
- `POST https://api.mcp.ai/api/bolna/create/knowledgebase` — Tool to create a new knowledgebase for Voice AI agents to reference during conversations. Use when you need to provide agents with domain-specific knowledge from PDFs or web URLs. Note: Initially retu
  - body: { url?: string, file?: object, user_id?: string, chunk_size?: integer, overlapping?: integer, is_api_request?: boolean, sub_account_id?: string, similarity_top_k?: integer }
- `POST https://api.mcp.ai/api/bolna/create/template/agent` — Tool to create a new Bolna Voice AI agent from a template. Use when you want to quickly set up an agent using predefined templates instead of building from scratch.
  - body: { prompt?: string, user_id?: string, agent_name?: string, agent_type?: string, transcript?: boolean, business_name?: string, return_prompt?: boolean, variable_dict?: object, about_business?: string, is_api_request?: string, template_agent?: string, service_details?: string }
- `POST https://api.mcp.ai/api/bolna/delete/agent/by/id` — Permanently delete a Voice AI agent and all associated data including batches, executions, and configurations
  - body: { agent_id: string }
- `POST https://api.mcp.ai/api/bolna/delete/batch/by/id` — Permanently delete a batch campaign by its ID, removing it from the system. This operation cannot be undone.
  - body: { batch_id: string }
- `POST https://api.mcp.ai/api/bolna/delete/knowledgebase` — Tool to permanently delete a knowledgebase from your Bolna account. Use when you need to remove an existing RAG knowledgebase that is no longer needed. This operation cannot be undone.
  - body: { rag_id: string, user_id?: string, is_api_request?: string, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/fetch/all/batches/by/agent/id` — Retrieve all batches associated with a specific Bolna Voice AI agent. Returns a comprehensive list of batches with details including batch status (scheduled, created, queued, executed), creation and s
  - body: { agent_id: string }
- `POST https://api.mcp.ai/api/bolna/get/agent/v1` — [DEPRECATED] Retrieve Voice AI agent details using the v1 API endpoint. Use GET /v2/agent/{agent_id} (retrieve_agent_by_id) instead for current implementations. This action returns agent configuration
  - body: { user_id?: string, agent_uuid: string, is_api_request?: string, sub_account_id?: string, agent_version_id?: string }
- `POST https://api.mcp.ai/api/bolna/get/all/agents` — Retrieve all agents configured in your Bolna account Returns a comprehensive list of all voice agents with their configurations including: - Agent metadata (ID, name, type, status) - Task configuratio
- `POST https://api.mcp.ai/api/bolna/get/execution/by/id` — Retrieve detailed information about a specific phone call execution by its ID. Returns comprehensive execution data including conversation transcript, duration, costs (LLM, TTS, STT, network, platform
  - body: { execution_id: string }
- `POST https://api.mcp.ai/api/bolna/get/knowledgebase` — Tool to retrieve details of a specific knowledgebase by its ID. Returns complete configuration including processing status, file information, vector ID, and embedding parameters (chunk size, similarit
  - body: { rag_id: string, user_id?: string, is_api_request?: boolean, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/get/user/info` — Tool to retrieve information about the authenticated user. Use when you need details like name, email, wallet balance, or concurrency limits for the current user.
  - body: { user_id?: string, is_api_request?: boolean }
- `POST https://api.mcp.ai/api/bolna/import/agent` — Tool to import an existing Bolna voice AI agent by its ID. Use when you need to copy or duplicate an agent configuration, create a new agent from a template, or migrate an agent from another environme
  - body: { user_id?: string, agent_id: string, agent_name?: string, is_api_request?: boolean, sub_account_id?: string, agent_version_id?: string }
- `POST https://api.mcp.ai/api/bolna/list/agents/paginated` — Tool to retrieve a paginated list of all agents in your Bolna account. Use when you need to fetch agents with optional filtering by user_id or sub_account_id.
  - body: { user_id?: string, page_size?: integer, page_number?: integer, is_api_request?: string, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/list/knowledgebases` — Tool to retrieve all knowledgebases from your Bolna account. Use when you need to view available RAG knowledgebases, check their processing status, or find specific knowledgebases by status.
  - body: { status?: string, user_id?: string, page_size?: integer, page_number?: integer, is_api_request?: string, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/list/phone/numbers` — Tool to list all phone numbers associated with your Bolna account. Use when you need to retrieve details of all phone numbers including provider, associated agent, pricing, and rental status.
- `POST https://api.mcp.ai/api/bolna/list/providers` — Retrieve all providers associated with your Bolna account Returns a list of all configured providers including: - Provider IDs (unique identifiers) - Provider names (e.g., API key types) - Masked prov
- `POST https://api.mcp.ai/api/bolna/list/voices` — Tool to list all available voices that can be utilized for Voice AI agents. Use when you need to see which voices are available across different providers.
  - body: { user_id?: string, is_api_request?: string }
- `POST https://api.mcp.ai/api/bolna/make/a/phone/call/from/agent` — Initiate an outbound phone call using a configured Bolna Voice AI agent. The agent will call the specified recipient and engage in a conversation based on its configured prompt and capabilities.
  - body: { agent_id: string, user_data?: object, from_phone_number?: string, recipient_phone_number: string }
- `POST https://api.mcp.ai/api/bolna/patch/agent/v1` — Tool to partially update a Voice AI agent using the v1 API endpoint. Use when you need to modify specific agent properties like name, welcome message, webhook URL, synthesizer settings, or system prom
  - body: { user_id?: string, agent_uuid: string, agent_config?: object, agent_prompts?: object, is_api_request?: boolean, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/remove/provider` — Tool to remove a provider from your Bolna account by its key name. Use when you need to delete a provider configuration that is no longer needed or needs to be replaced.
  - body: { user_id?: string, is_api_request?: boolean, sub_account_id?: string, provider_key_name: string }
- `POST https://api.mcp.ai/api/bolna/retrieve/agent/by/id` — Retrieve complete configuration and details for a specific Bolna voice AI agent by its ID. Returns comprehensive agent information including name, type, status, conversation tasks, LLM/synthesizer/tra
  - body: { agent_id: string }
- `POST https://api.mcp.ai/api/bolna/retrieve/agent/execution/details` — Retrieve detailed information about a specific execution (call/conversation) by an agent, including transcript, costs, duration, status, and telephony data
  - body: { agent_id: string, execution_id: string }
- `POST https://api.mcp.ai/api/bolna/retrieve/agent/execution/status` — Retrieve all executions for a specific agent with pagination and filtering support. Returns a paginated list of agent execution records including call status, cost breakdown, transcripts, and telephon
  - body: { to?: string, from?: string, status?: string, agent_id: string, batch_id?: string, provider?: string, call_type?: string, page_size?: integer, page_number?: integer, answered_by_voice_mail?: boolean }
- `POST https://api.mcp.ai/api/bolna/retrieve/batch/details/by/id` — Retrieve comprehensive details about a specific Bolna batch by its ID. Returns batch metadata including creation time, execution status, scheduled time, contact statistics, and call status breakdown. 
  - body: { batch_id: string }
- `POST https://api.mcp.ai/api/bolna/retrieve/batch/execution/list` — Retrieve all executions from a specific batch with pagination support. Returns detailed information about each call execution including conversation metrics, transcripts, costs, and resource usage bre
  - body: { batch_id: string, page_size?: integer, page_number?: integer }
- `POST https://api.mcp.ai/api/bolna/schedule/batch/by/id` — Schedule a batch to execute at a specific time. After creating a batch with BOLNA_CREATE_BATCH, use this action to set when the batch calls should begin. The batch must exist and be in a schedulable s
  - body: { batch_id: string, scheduled_at: string }
- `POST https://api.mcp.ai/api/bolna/search/phone/numbers` — Tool to search for available phone numbers that can be purchased for Bolna Voice agents. Use when you need to find purchasable phone numbers by country or prefix pattern before buying.
  - body: { country: string, pattern?: string }
- `POST https://api.mcp.ai/api/bolna/setup/inbound/call/for/agent` — Add agent for inbound calls
  - body: { agent_id: string, phone_number_id: string }
- `POST https://api.mcp.ai/api/bolna/stop/agent/calls` — Tool to stop all queued or scheduled calls for a specific Voice AI agent. Use when you need to immediately halt all pending calls for an agent.
  - body: { user_id?: string, agent_id: string, is_api_request?: boolean, sub_account_id?: string }
- `POST https://api.mcp.ai/api/bolna/stop/batch/by/id` — Stop a running batch by its ID. This halts all queued calls in the batch. Any calls currently in the queue waiting to be executed will be cancelled and will not be processed. Use this when you need to
  - body: { batch_id: string }
- `POST https://api.mcp.ai/api/bolna/update/agent` — Tool to update all settings and configuration of an existing Bolna Voice AI agent using the v2 API. Use when you need to modify an agent's full configuration including LLM settings, synthesizer, trans
  - body: { user_id?: string, agent_id: string, agent_config: object, agent_prompts: object, is_api_request?: boolean, sub_account_id?: string }

## Example prompts
- "What can I do in Bolna?"
- "Show me a summary of my Bolna account"

## More
- Page: https://mcp.ai/bolna
- Agent spec (llms.txt): https://mcp.ai/bolna/llms.txt
- Postman collection: https://mcp.ai/bolna/postman.json