Vobiz

Vobiz MCP server

The official Model Context Protocol server for Vobiz. It lets Claude and any other MCP client run real work on your Vobiz account:

• place and control voice calls, run conferences, and stream call audio to AI agents
• build VobizXML IVRs
• read call records and recordings
• manage phone numbers, SIP trunks, credentials, IP allow-lists, SIP endpoints, voice applications and sub-accounts
• read billing transactions
• send SMS, MMS and RCS messages
• schedule reminder and wake-up calls (hosted connector)
• call someone and play audio or speak text in one step: make_call with say / play (hosted connector)

It also ships the Vobiz Agent Skills, so the model knows how each Vobiz product works before it acts.

[CI] [npm] [MCP Registry] [License: MIT] [Glama]

Looking for documentation search instead of account operations? Use the hosted Vobiz Docs MCP server (https://www.vobiz.ai/docs/mcp). The two servers work well side by side.

"Call me at…"

On the hosted connector (https://mcp.vobiz.ai/mcp) you can say "wake me up at 6 tomorrow" or "call me at 3 to remind me about the dentist". The client calls schedule_reminder_call once and the server does the rest: it places the call at that time from your Vobiz number, speaks the message, and lets you press 1 to snooze, 2 to confirm or 9 to stop. It retries when nobody answers. Nothing depends on the chat staying open.

At sign-in you choose Full access, Personal assistant (only reminder calls to your own number, plus your balance, numbers and call status) or Read-only, and enter your own number, an optional caller ID and your timezone. Manage reminders with list_reminder_calls, get_reminder_call and cancel_reminder_call. Operators: see docs/HOSTING.md.

"Call me and play this"

On the hosted connector, "call +919876543210 and play my alarm" or "call +919876543210 and say 'Your table is ready'" is one make_call with say (text) and/or play (a file in your audio library, or a direct https .mp3/.wav link). The connector hosts the call script: the call plays or speaks the content, then hangs up (loop: 0 repeats the audio until you hang up). A web page such as Pixabay, YouTube, Spotify or SoundCloud cannot be played; give a direct file link or add the file to your audio library first. See docs/TOOLS.md.

Your own audio on a reminder call

Say "use this MP3 as my alarm" or "let me record the message". Your audio plays at the start of the call, before the spoken message. There are three ways to add it to your private audio library:

• Upload page. create_audio_upload_link gives you a one-time link (valid 15 minutes). Open it to pick or drop a file, or press Record to record from your microphone (up to 5 minutes), then name it.
• Straight from the chat. If you attached the file and your assistant can run code, it uploads the file to the same link itself.
• A public link. Paste an https link and the assistant saves it with import_audio_from_url.

Then say "use the audio Morning alarm" and the assistant passes that name as audio to schedule_reminder_call. MP3, WAV, M4A, OGG, WEBM, AAC and FLAC work, up to 15 MB and 5 minutes each. See your files with list_audio and remove one with delete_audio. Operators: see docs/HOSTING.md.

Contents

• What you can ask
• Connect Claude in five steps
• Install (every client: docs/INSTALL.md)
• Tools
• Skills, prompts and resources
• Safety model
• Configuration
• Run modes
• Hosted connector (OAuth)
• Privacy policy
• Development
• Troubleshooting
• Related

What you can ask

Connect Claude in five steps

Works in claude.ai, Claude Desktop and the Claude mobile apps. Nothing to install.

1. Copy your credentials. In the Vobiz console overview page, copy your Auth ID (MA_…, or SA_… for a sub-account) and Auth Token.
2. Open Connectors. In Claude, go to Settings → Connectors → Add custom connector. On Team and Enterprise plans an Owner adds it once under Admin settings → Connectors, then each member connects their own Vobiz account.
3. Add the server. Name it Vobiz, enter https://mcp.vobiz.ai/mcp, leave the advanced OAuth fields empty, and click Add.
4. Connect and sign in. Click Connect. On the Vobiz sign-in page, paste your Auth ID and Auth Token, optionally tick Read-only access, and click Allow access. You return to Claude, connected.
5. Use it. In a new chat, enable Vobiz in the tools menu and ask: "What's my Vobiz balance, and how many calls are live right now?"

Claude asks before it runs any tool that places a call, sends a message or changes your account, and the server requires your confirmation for each one. Number purchases are not offered by the hosted connector.

Install

You need a Vobiz account, plus its Auth ID and Auth Token from the overview page of the Vobiz console. The full guide, with config files for every client, is docs/INSTALL.md.

Connect in one step (hosted, recommended)

Every remote option signs in with OAuth on a Vobiz page, so no Auth Token is written to a config file. To run the server on your own machine instead, use the local options below.

Run it locally

Local options run the server on your machine with npx and need Node.js 22.9 or newer.

Any other MCP client:

{  "mcpServers": {    "vobiz": {      "command": "npx",      "args": [        "-y",        "@vobiz/[email protected]"      ],      "env": {        "VOBIZ_AUTH_ID": "MA_XXXXXXXX",        "VOBIZ_AUTH_TOKEN": "YOUR_AUTH_TOKEN"      }    }  }}

Calling, messaging and account changes stay off until you add VOBIZ_ENABLE_CALLS, VOBIZ_ENABLE_MESSAGING or VOBIZ_ENABLE_PROVISIONING set to "true" to env.

To self-host the remote connector: docker run -p 3000:3000 -e VOBIZ_HOSTED_URL=https://mcp.example.com -e VOBIZ_HOSTED_SECRET="$(openssl rand -hex 32)" ghcr.io/vobiz-ai/vobiz-mcp:v1.4.4 (docs/HOSTING.md).

Tools

Every tool has a title, input validation, and annotations: readOnlyHint: true or destructiveHint: true, plus idempotentHint and openWorldHint. Results are structuredContent, with the same JSON sent as text. docs/TOOLS.md lists every input and is generated from the registry.

Choosing tools. 114 tools is a lot for some clients. Load only what you need:

• VOBIZ_TOOLSETS=calls,call_control,records,skills registers just those groups.
• VOBIZ_READ_ONLY=true keeps only the read-only tools.

Secrets. SIP passwords, credential secrets and sub-account tokens are always redacted. Reset or copy them in the Vobiz console.

Hosting needed. gather_dtmf, get_gather_result, list_webhook_events, hold_call and unhold_call need Vobiz to reach this server. Use single-account HTTP mode with VOBIZ_PUBLIC_URL for them.

Errors. Errors are MCP tool errors (isError: true) shaped like this:

{ "ok": false, "error": "not_allowed", "message": "…what happened and what to do…", "retryable": false, "http_status": 400, "hint": "…" }

Error kinds.

• Input and access: invalid_input, missing_credentials, auth_failed, forbidden, not_found, insufficient_balance
• Limits and availability: rate_limited, timeout, network_error, service_unavailable
• Server switches and policy: calls_disabled, messaging_disabled, provisioning_disabled, confirmation_required, not_allowed, spending_limit
• Idempotency: duplicate_blocked, idempotency_conflict, in_progress, outcome_unknown
• Other: call_not_active, opted_out, unsupported, internal_error

Call outcomes. Call results add outcome (answered, busy, no_answer, rejected, invalid_number, unreachable, cancelled…) with the typical SIP code.

Skills, prompts and resources

The 17 Vobiz Agent Skills ship inside the package (skills/) and are exposed three ways, so they work in every client:

The skills:

• Voice and calls: vobiz-api, vobiz-voice-calls, vobiz-voice-xml, vobiz-audio-streams, vobiz-cdr
• Campaigns and reporting: vobiz-campaign-planner, vobiz-reports
• Numbers and infrastructure: vobiz-phone-numbers, vobiz-sip-trunking, vobiz-applications-endpoints
• AI and messaging: vobiz-ai-voice-agents, vobiz-sms, vobiz-whatsapp
• Accounts and partners: vobiz-sub-accounts, vobiz-partner-api
• Migration and scoping: vobiz-plivo-migration, vobiz-forward-deployed-engineer

The skills come from the Vobiz docs repository. Refresh them with npm run skills:sync [path/to/.mintlify/skills].

Safety model

Everything below is enforced by the server, not left to the model.

Configuration

All settings are environment variables. Every one is optional except credentials (and the hosted settings for hosted mode). .env.example lists them all with comments.

Run modes

| Mode | Command | For | |---|---|---|---| | stdio | npx -y @vobiz/mcp (or node dist/index.js) | Claude Desktop, Claude Code, Cursor and other local clients on one account | | Single-account HTTP | npx -y @vobiz/mcp http (or npm run start:http) | One account over Streamable HTTP behind a path secret; hosted IVR flows, gather, signed webhooks | | Hosted multi-tenant | npx -y @vobiz/mcp hosted (or npm run start:hosted, Docker) | Public connector: each user signs in with OAuth and acts only on their own account | | Dashboard | npm run dashboard → http://127.0.0.1:5178 | Read-only local browser view built on the same tools |

Single-account HTTP endpoints

| Path | Purpose | Auth | |---|---|---|---| | /mcp/<VOBIZ_HTTP_SECRET> | Streamable HTTP MCP | path secret | | /sse/<secret>, /message/<secret> | legacy SSE MCP for older clients | path secret | | /xml/flow/<id> | hosted XML (answer, transfer, hold, dial) | Vobiz signature + 128-bit ID | | /xml/gather/<id> | Gather Digits callback; returns follow-up XML | Vobiz signature + ID | | /webhooks/vobiz | answer, hangup and status callbacks | Vobiz signature | | /answer | static <Speak> XML | none | | /health | liveness | none |

Callback signatures. Callbacks are checked with X-Vobiz-Signature-V3 = base64(HMAC-SHA256(auth_token, URL-without-query + "." + nonce)). V2 is accepted as a fallback, and the comparison is constant-time. Reused nonces are rejected, and duplicate events are stored once.

Hosted connector (OAuth)

vobiz-mcp hosted is a complete OAuth 2.1 authorization server and MCP resource server in one process. It is built for Claude's connector directory and works with any remote MCP client.

Sign-in flow:

1. Claude calls POST /mcp without a token. The server answers 401 with WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp".
2. Claude reads the protected-resource metadata (RFC 9728, resource = <VOBIZ_HOSTED_URL>/mcp) and the authorization-server metadata (RFC 8414). The AS metadata advertises PKCE S256, dynamic client registration (RFC 7591) and Client ID Metadata Documents.
3. Claude registers itself, or uses its CIMD URL, and opens /authorize. The user enters their Auth ID and Auth Token and picks Full access, Personal assistant or Read-only, plus their own number, caller ID and timezone for reminder calls. The server checks the credentials with Vobiz, then redirects back with a single-use code.
4. /token exchanges the code (PKCE checked) for a 1-hour access token and a 30-day refresh token.

Token handling:

• Tokens are AES-256-GCM sealed, so no credential database is needed and any number of replicas can share VOBIZ_HOSTED_SECRET.
• Each request runs on the signed-in account only, with per-account rate limits and idempotency.
• Rotating the Auth Token in the Vobiz console revokes every token for that account immediately.

Server card. GET https://mcp.vobiz.ai/mcp/server-card (alias /.well-known/mcp/server-card.json) serves an MCP server card: the server's name, version, Streamable HTTP endpoint and supported protocol versions, for clients and scanners that discover servers before connecting. It is public, cached for an hour and lists no tools; those come from tools/list after sign-in.

Tool exclusions. The hosted connector leaves out tools that buy things or need the server to host one account's callbacks. The default list is buy_phone_number, gather_dtmf, get_gather_result, list_webhook_events, hold_call and unhold_call, and you can change it with VOBIZ_HOSTED_EXCLUDED_TOOLS. Browser Origin headers are checked against VOBIZ_ALLOWED_ORIGINS.

Deployment, DNS, scaling and directory submission are covered in docs/HOSTING.md and docs/PUBLISHING.md.

Privacy policy

This server is published by Vobiz (Ilaimitado Private Limited). The full policy is at https://www.vobiz.ai/privacy.

What it processes:

• Your Vobiz Auth ID and Auth Token, used only to authenticate your requests to the Vobiz API.
• The tool arguments the MCP client sends, such as phone numbers, message text and call settings.
• The Vobiz API responses it returns to the client.

What it stores:

• Local modes: credentials stay in your environment or OS keychain. Idempotency records stay in memory, or in VOBIZ_IDEMPOTENCY_FILE if you set it.
• Hosted mode (https://mcp.vobiz.ai/mcp): the connector stores no conversation content. Your Vobiz Auth ID and Auth Token are kept only inside encrypted (AES-256-GCM), expiring tokens: the access and refresh tokens your MCP client holds and, while a reminder call is pending, its queued call job. It stores:

| Item | Location | Retention | |---|---|---|---| | Idempotency records for calls, messages and number purchases (key, request fingerprint, the tool result) | Firestore | Up to 24 hours | | Rate counters for calls and messages (per account, per minute and per hour) | Firestore | Until the window ends (at most 1 hour) | | OAuth sessions (refresh-token family: ids, timestamps, a hash of the Auth ID; refresh tokens rotate with reuse detection) and used authorization codes | Firestore | Up to 90 days per session; codes expire after 5 minutes | | Reminder calls (destination number, message text, timezone, caller ID, schedule and the outcome of each attempt) | Firestore | Kept as your reminder history; cancel_reminder_call stops a pending one | | Audio library files and their names | Private Cloud Storage bucket, under a hash of the Auth ID | Until you delete them with delete_audio |

What it never does: it does not read your conversation history, memory or files. It does not use your data for advertising, and it does not sell or share it with third parties.

Logs: logs contain route templates, HTTP status codes and timings. They never contain tokens, message text or phone numbers.

Retention: call records, recordings and messages remain in your Vobiz account under the Vobiz terms (https://www.vobiz.ai/terms).

Contact: [email protected]

Development

git clone https://github.com/vobiz-ai/Vobiz-MCP-Server.gitcd Vobiz-MCP-Servernpm cicp .env.example .env        # placeholders only; fill in your own credentialsnpm run check               # type-check, build, mocked testsnpm run test:live           # live read-only smoke test with .env credentials (calls/messages/purchases forced off)npm run test:live:hosted    # live OAuth flow + hosted tools against the real API (no messages sent)npm run inspector           # MCP Inspector against dist/index.jsnpm run docs:tools          # regenerate docs/TOOLS.mdnpm run skills:sync         # refresh bundled skills from the docs repository

Code layout:

• Tools live in src/tools/{calls,control,conferences,media,records,account,voice,provisioning,sip,subaccounts,messaging}.ts. Each file is one toolset, registered in src/server.ts.
• Skills are in src/skills.ts.
• Guardrails are in src/policy.ts, src/idempotency.ts and src/outcomes.ts.
• VobizXML generation is in src/xml.ts, hosted flows in src/flows.ts, and callback verification in src/webhooks.ts.
• Transports are in src/index.ts (stdio), src/http.ts (single account) and src/hosted.ts (OAuth multi-tenant).

Tests:

• Mocked tests never touch the network, and no test places a call, sends a message or buys a number.
• CI runs lint, build, the tests on Node 22 and 24, npm audit, the .mcpb manifest check and a package dry-run.
• Releases are tag-driven (v1.2.3). They publish to npm with provenance and to the MCP Registry, attach the .mcpb bundle, and push the Docker image (see docs/PUBLISHING.md).

Troubleshooting

Related

• Vobiz CLI (GitHub, docs): run vobiz mcp install <client> to add this server to Claude Code, Cursor, Codex, VS Code, Gemini CLI, Windsurf, Zed or Claude Desktop. It uses the hosted connector with OAuth sign-in by default.
• Vobiz Agent Skills (GitHub, docs): the same skills bundled here, packaged for any agent that loads skills.

Built by Team Vobiz

Vobiz is a global programmable telephony platform: SIP trunking, voice APIs, SMS, WhatsApp and AI voice agent integrations in 130+ countries.

Support: [email protected] · Documentation · Issues · Contributing · Security · Code of Conduct

License

MIT © Vobiz