> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Drive Voicebip from an AI Assistant (MCP)

> Connect the Voicebip MCP server and let an AI assistant (Claude, Cursor, any MCP client) provision numbers, build agents, launch campaigns, and read analytics — conversationally.

**What you build:** Voicebip wired into an AI coding assistant or agent via the **Model Context Protocol (MCP)**. Once connected, the assistant can call Voicebip's REST surface through **46 tools** — so you can say "provision a Lagos number, attach it to my support agent, and place a test call" and it happens, no curl required.

```
You (in Claude / Cursor) ──▶ MCP client ──▶ Voicebip MCP server ──▶ voicebip-api (REST)
   "provision a number and call +234…"        (46 tools, X-API-Key)
```

**Who it's for:** developers who live in an AI IDE, teams building agentic ops tooling, and anyone who'd rather describe an outcome than hand-write API calls.

## Prerequisites

* A Voicebip API key (`pk_live_…` or `pk_test_…`).
* An MCP-capable client (Claude Desktop, Cursor, or any MCP host).
* Node 20+ (the server is TypeScript/Node).

## Step 1 — Configure the MCP server

Add Voicebip to your MCP client config. The server authenticates with your key via the `VOICEBIP_API_KEY` env var — the workspace is derived from the key, so **no `workspace_id` is ever passed to a tool**:

```json
{
  "mcpServers": {
    "voicebip": {
      "command": "npx",
      "args": ["-y", "@voicebip/mcp"],
      "env": { "VOICEBIP_API_KEY": "pk_test_xxx" }
    }
  }
}
```

Restart the client; it discovers the 46 tools. Full setup (Claude Desktop, Cursor, troubleshooting) is in the [MCP Server overview](/integrations/mcp/overview).

## Step 2 — What the assistant can do (tool catalogue)

The tools mirror the REST API, grouped by resource:

| Category                | Tools                                                                                                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agents** (7)          | `create_agent`, `list_agents`, `get_agent`, `update_agent`, `delete_agent`, `toggle_agent_shareable`, `export_conversations`                                                        |
| **Numbers** (4)         | `provision_number`, `list_available_numbers`, `get_number`, `release_number`                                                                                                        |
| **Calls** (8)           | `make_call`, `get_call`, `end_call`, `get_call_recording`, `hold_call`, `resume_call`, `transfer_call`, `send_dtmf`                                                                 |
| **Messaging** (5)       | `send_message`, `send_template`, `get_conversation`, `list_conversations`, `update_conversation_mode`                                                                               |
| **Knowledge Bases** (7) | `create_knowledge_base`, `list_knowledge_bases`, `upload_knowledge_document`, `complete_knowledge_document`, `get_document_status`, `query_knowledge_base`, `attach_knowledge_base` |
| **Routing** (5)         | `list_routing_rules`, `create_routing_rule`, `update_routing_rule`, `delete_routing_rule`, `get_analytics`                                                                          |
| **API Keys** (4)        | `create_api_key`, `list_api_keys`, `revoke_api_key`, `rotate_api_key`                                                                                                               |
| **Subscription** (2)    | `get_subscription`, `update_subscription`                                                                                                                                           |
| **Misc** (3)            | `test_webhook`, `get_usage`, `list_templates`                                                                                                                                       |

## Step 3 — A sample session

Ask the assistant in plain language; it chooses and chains tools:

> **You:** Create a support agent grounded in kb_8sd2k1fapvq3, provision a Lagos number for it, then make a test call to +2348031234567.

The assistant runs, roughly:

```
→ create_agent({ display_name: "Support", ai_provider: "hosted",
                 knowledge_base_id: "kb_8sd2k1fapvq3", tts_voice: "<voice_id>" })
    ← agt_PAE…
→ list_available_numbers({ type: "geo_did", area_code: "01" })
    ← num_7hq… (+2341002223344)
→ provision_number({ number_id: "num_7hq…", agent_id: "agt_PAE…", channels: ["voice"] })
    ← +2341002223344 bound to agt_PAE…
→ make_call({ agent_id: "agt_PAE…", from_number: "+2341002223344", to_number: "+2348031234567" })
    ← call_5xk… (queued)
```

Note the ordering: the agent is created first, then `provision_number` **binds the number to it at provision time** (there's no separate "attach" step). Every tool returns structured results (`{ error_code, message, suggested_fix }` on failure), so the assistant can self-correct — e.g. retry with a valid E.164 if `make_call` rejects the number.

## Step 4 — Keep it safe

* Use a **`pk_test_` key** while iterating so the assistant operates entirely in the sandbox (₦0, no real calls). Swap to `pk_live_` only when you mean it.
* Scope the key: create a dedicated API key (`create_api_key`) for the MCP client so you can `revoke_api_key` it independently.
* The workspace is bound to the key — the assistant can never reach another tenant's data.

## Test it (sandbox)

With a `pk_test_` key in the config, ask the assistant to "send a test webhook for a completed call" — it calls `test_webhook`, and your endpoint receives a real-signed synthetic event. The whole tour above runs against the sandbox with no billing.

## Troubleshooting

| Symptom                          | Likely cause                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------ |
| Client shows no Voicebip tools   | Config not loaded / client not restarted; check the `mcpServers` block.        |
| Every tool returns auth error    | `VOICEBIP_API_KEY` unset or invalid in `env`.                                  |
| Assistant "can't find workspace" | Don't pass `workspace_id` — it's derived from the key; remove it from prompts. |
| Real calls placed unexpectedly   | You're on a `pk_live_` key — switch to `pk_test_` for experiments.             |

## Next steps

* Deep setup + client-specific configs → [MCP Server overview](/integrations/mcp/overview).
* Build the agents the assistant will manage → [Inbound support + KB](/use-cases/inbound-support-kb).
* Prefer code? Every tool maps 1:1 to the [REST API](/api).