Use Cases

Drive Voicebip from an AI Assistant (MCP)

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:

1{
2  "mcpServers": {
3    "voicebip": {
4      "command": "npx",
5      "args": ["-y", "@voicebip/mcp"],
6      "env": { "VOICEBIP_API_KEY": "pk_test_xxx" }
7    }
8  }
9}

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

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

The tools mirror the REST API, grouped by resource:

CategoryTools
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

SymptomLikely cause
Client shows no Voicebip toolsConfig not loaded / client not restarted; check the mcpServers block.
Every tool returns auth errorVOICEBIP_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 unexpectedlyYou’re on a pk_live_ key — switch to pk_test_ for experiments.

Next steps