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

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

imageCI imagenpm imageMCP Registry imageLicense: MIT

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.

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

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/mcp@1.1.4"
      ],
      "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.1.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. 106 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 15 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
• 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

Single-account HTTP endpoints

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 can tick read-only access. 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.

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: the server keeps no credential or conversation database. Credentials travel inside encrypted, expiring tokens held by your MCP client. Per-account rate-limit counters and idempotency records live in memory for up to 24 hours.

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: support@vobiz.ai

Development

git clone https://github.com/vobiz-ai/Vobiz-MCP-Server.git
cd Vobiz-MCP-Server
npm ci
cp .env.example .env        # placeholders only; fill in your own credentials
npm run check               # type-check, build, 253 mocked tests
npm 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.js
npm run docs:tools          # regenerate docs/TOOLS.md
npm 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

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: support@vobiz.ai · Documentation · Issues · Contributing · Security · Code of Conduct

License

MIT © Vobiz