> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vobiz MCP Server

> Let Claude, Cursor, VS Code and other AI clients work on your Vobiz account through the Model Context Protocol: place and control calls, build IVRs, read call records, manage numbers and SIP trunks, and send SMS, MMS and RCS, with confirmation on every action.

The **Vobiz MCP server** connects an AI client to your own Vobiz account. With it, Claude (or any MCP client) can:

* check your balance, billing transactions, live calls and call history
* place and control calls and conferences, stream call audio to your AI agent, and build VobizXML IVRs
* manage phone numbers, SIP trunks, credentials, IP allow-lists, SIP endpoints, voice applications and sub-accounts
* send and track SMS, MMS and RCS messages

It also ships the [Vobiz Agent Skills](/docs/resources/skills), so the model follows the right endpoints and VobizXML rules.

<Note>
  This server acts on your account. To search the documentation instead, use the [Vobiz Docs MCP server](/docs/resources/mcp). The two work well side by side.
</Note>

| | |
| - | - |
| Source | [github.com/vobiz-ai/Vobiz-MCP-Server](https://github.com/vobiz-ai/Vobiz-MCP-Server) (MIT) |
| Install guides | [Connect any client in one step](#connect-any-client-in-one-step), or the full [INSTALL.md](https://github.com/vobiz-ai/Vobiz-MCP-Server/blob/main/docs/INSTALL.md) |
| Hosted connector | `https://mcp.vobiz.ai/mcp` (Streamable HTTP, OAuth sign-in) |
| Package | [`@vobiz/mcp`](https://www.npmjs.com/package/@vobiz/mcp) on npm |
| Registry name | `io.github.vobiz-ai/vobiz-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.vobiz-ai/vobiz-mcp) |
| Tools | 106 in 12 toolsets: calls, in-call control, conferences, audio streams, IVR/XML, call records, numbers, SIP trunks and endpoints, applications, sub-accounts, billing, SMS/MMS/RCS, opt-outs, skills |
| Prompts and resources | One prompt per Vobiz skill, plus `vobiz://skills/{name}` resources |

## Prerequisites

* A Vobiz account and its **Auth ID** and **Auth Token**, from the overview page of the [Vobiz console](https://console.vobiz.ai).
* Node.js 22.9 or newer for the local options (`node --version`).

## Connect Claude step by step

The hosted connector works in claude.ai, Claude Desktop and the Claude mobile apps. There is nothing to install: you add a URL and sign in with your Vobiz credentials.

<Steps>
  <Step title="Copy your Vobiz credentials">
    Sign in to the [Vobiz console](https://console.vobiz.ai). On the overview page, copy your **Auth ID** (it starts with `MA_`, or `SA_` for a sub-account) and your **Auth Token**.
  </Step>

  <Step title="Open Connectors in Claude">
    In claude.ai or Claude Desktop, open **Settings → Connectors** and click **Add custom connector**.

    On a Team or Enterprise plan, an Owner adds custom connectors for the organization under **Admin settings → Connectors**. Members then connect their own Vobiz account in **Settings → Connectors**.
  </Step>

  <Step title="Add the Vobiz MCP server">
    Enter a name, for example `Vobiz`, and the URL:

    ```text theme={null}
    https://mcp.vobiz.ai/mcp
    ```

    Leave the advanced OAuth fields empty, then click **Add**.
  </Step>

  <Step title="Connect and sign in">
    Click **Connect**. A Vobiz sign-in page opens and shows which app is asking for access.

    1. Paste your **Auth ID** and **Auth Token**.
    2. Optional: tick **Read-only access** to let Claude look at your account without placing calls, sending messages or changing settings.
    3. Click **Allow access**.

    You return to Claude and the connector shows as connected.
  </Step>

  <Step title="Turn on the tools in a chat">
    Start a new chat, open the tools menu in the message box and make sure **Vobiz** is enabled. Then try:

    ```text theme={null}
    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 also needs your confirmation for each one.
  </Step>
</Steps>

Your Auth ID and Auth Token are sealed inside the access token that Claude holds. The Vobiz MCP server does not store them.

### Change access or disconnect

| To | Do this |
| - | - |
| Switch between read-only and full access | **Settings → Connectors → Vobiz → Disconnect**, then **Connect** again and change the **Read-only access** box. |
| Disconnect Claude | **Settings → Connectors → Vobiz → Disconnect** (or remove the connector). |
| Revoke every app at once | Rotate your Auth Token in the [Vobiz console](https://console.vobiz.ai). Every connection signed in with the old token stops working immediately. |

### If something goes wrong

| What you see | What to do |
| - | - |
| "Vobiz did not accept this Auth ID and Auth Token" | Copy both values again from the console overview page. Check for a missing character or a trailing space. |
| "This sign-in link has expired" | The sign-in page is valid for 15 minutes. Go back to Claude and click **Connect** again. |
| A tool says calling or messaging is disabled | You connected with **Read-only access**. Disconnect and connect again without it. |
| `forbidden` on account details | Account details need main-account (`MA_`) credentials. Sub-account (`SA_`) credentials still work for calls, numbers and messages. |

## Connect any client in one step

Every client below connects to the hosted server and signs you in on a Vobiz page, so no Auth Token goes in a config file.

| Client | One step | Then |
| - | - | - |
| Claude (web, Desktop, mobile) | **Settings → Connectors → Add custom connector** → `https://mcp.vobiz.ai/mcp` | Click **Connect** and sign in ([steps above](#connect-claude-step-by-step)) |
| Claude Code | `claude mcp add --transport http vobiz https://mcp.vobiz.ai/mcp` | Run `/mcp`, pick **vobiz**, sign in |
| Claude Code plugin (server and skills) | `/plugin install vobiz --marketplace vobiz-ai/Vobiz-MCP-Server` | Enter your Auth ID and Auth Token when asked |
| OpenAI Codex (CLI, IDE, app) | `codex mcp add vobiz --url https://mcp.vobiz.ai/mcp` | The Vobiz sign-in opens automatically |
| ChatGPT | **Plugins → + → Add custom MCP server** → `https://mcp.vobiz.ai/mcp` | Sign in, then use **@Vobiz** |
| Gemini CLI | `gemini mcp add -s user --transport http vobiz https://mcp.vobiz.ai/mcp` | Run `/mcp auth vobiz` |
| Cursor | [Add to Cursor](https://cursor.com/en/install-mcp?name=vobiz\&config=eyJ1cmwiOiJodHRwczovL21jcC52b2Jpei5haS9tY3AifQ%3D%3D) | Click **Connect** in Cursor's MCP settings |
| VS Code / GitHub Copilot | [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=vobiz\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.vobiz.ai%2Fmcp%22%7D) | Start the server and sign in |
| Windsurf / Devin | `devin mcp add -s user vobiz https://mcp.vobiz.ai/mcp` | `devin mcp login vobiz` |
| Cline | `cline mcp add vobiz https://mcp.vobiz.ai/mcp --transport http --yes` | Choose **Authorize OAuth** |
| Zed, JetBrains, Warp, LM Studio, Continue, Goose | Add a server with URL `https://mcp.vobiz.ai/mcp` ([guide](https://github.com/vobiz-ai/Vobiz-MCP-Server/blob/main/docs/INSTALL.md)) | Sign in |

## npm package

The server is published on npm as [`@vobiz/mcp`](https://www.npmjs.com/package/@vobiz/mcp) and listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.vobiz-ai/vobiz-mcp) as `io.github.vobiz-ai/vobiz-mcp`. It needs Node.js 22.9 or newer.

<CodeGroup>
  ```bash Run without installing theme={null}
  VOBIZ_AUTH_ID=MA_XXXXXXXX VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN npx -y @vobiz/mcp
  ```

  ```bash Install globally theme={null}
  npm install -g @vobiz/mcp
  vobiz-mcp --version
  ```

  ```bash Pin a version theme={null}
  npx -y @vobiz/mcp@1.1.4
  ```
</CodeGroup>

MCP clients start the server for you from their config, so you rarely run it by hand. The `vobiz-mcp` command has three modes:

| Command | What it runs |
| - | - |
| `vobiz-mcp` | The server over stdio, for local MCP clients (Claude Desktop, Claude Code, Cursor, Codex and others) |
| `vobiz-mcp http` | One account over Streamable HTTP behind a path secret, for self-hosting |
| `vobiz-mcp hosted` | The multi-user connector with OAuth sign-in, the same software that runs `https://mcp.vobiz.ai/mcp` |
| `vobiz-mcp --help` / `--version` | Usage and the installed version |

Settings come from environment variables. `VOBIZ_AUTH_ID` and `VOBIZ_AUTH_TOKEN` are required for local use. The full list is in [`.env.example`](https://github.com/vobiz-ai/Vobiz-MCP-Server/blob/main/.env.example).

## Run it locally

To run the server on your own machine instead, pick your client. The local options need Node.js 22.9 or newer.

<Tabs>
  <Tab title="Claude Desktop extension">
    1. Download `vobiz-mcp-<version>.mcpb` from the [latest release](https://github.com/vobiz-ai/Vobiz-MCP-Server/releases/latest).
    2. Open the file. Claude Desktop shows the install screen.
    3. Enter your Auth ID and Auth Token, then choose whether Claude may place calls, send messages or change your account.

    The Auth Token is stored in your operating system's keychain.
  </Tab>

  <Tab title="Claude Code">
    Install the plugin. It adds this server, the [Vobiz Docs MCP server](/docs/resources/mcp) and all [Vobiz Agent Skills](/docs/resources/skills), and keeps your Auth Token in the OS credential store:

    ```text theme={null}
    /plugin install vobiz --marketplace vobiz-ai/Vobiz-MCP-Server
    ```

    Or add only this server:

    ```bash theme={null}
    claude mcp add vobiz \
      -e VOBIZ_AUTH_ID=MA_XXXXXXXX \
      -e VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN \
      -- npx -y @vobiz/mcp
    ```

    Or use the hosted connector, then run `/mcp` in Claude Code to sign in:

    ```bash theme={null}
    claude mcp add --transport http vobiz https://mcp.vobiz.ai/mcp
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add vobiz --env VOBIZ_AUTH_ID=MA_XXXXXXXX --env VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN -- npx -y @vobiz/mcp
    ```

    Or the hosted connector: `codex mcp add vobiz --url https://mcp.vobiz.ai/mcp`, then `codex mcp login vobiz`.
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={null}
    gemini extensions install https://github.com/vobiz-ai/Vobiz-MCP-Server
    ```

    Gemini asks for your Auth ID and Auth Token and keeps the token in the system keychain.
  </Tab>

  <Tab title="Cursor, VS Code and others">
    Add this to your client's MCP configuration (`~/.cursor/mcp.json`, `.vscode/mcp.json`, Windsurf, Cline and so on):

    ```json theme={null}
    {
      "mcpServers": {
        "vobiz": {
          "command": "npx",
          "args": ["-y", "@vobiz/mcp"],
          "env": {
            "VOBIZ_AUTH_ID": "MA_XXXXXXXX",
            "VOBIZ_AUTH_TOKEN": "YOUR_AUTH_TOKEN"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Turn on actions

With the **hosted connector**, calling, messaging and account changes are available unless you choose **Read-only access** when you sign in. Number purchases are not offered there.

When you run the server **locally** (desktop extension, plugin or `npx`), it reads your account and generates VobizXML out of the box. Calling, messaging and account changes stay off until you enable them:

| Capability | Local setting | Desktop extension |
| - | - | - |
| Place outbound calls | `VOBIZ_ENABLE_CALLS=true` | **Allow outbound calls** |
| Send SMS, MMS and RCS; change opt-outs | `VOBIZ_ENABLE_MESSAGING=true` | **Allow sending messages** |
| Buy or release numbers; change SIP trunks, endpoints, credentials, IP allow-lists, applications and sub-accounts; delete recordings | `VOBIZ_ENABLE_PROVISIONING=true` (purchases also need `VOBIZ_MAX_NUMBER_COST`) | **Allow account changes** |

When an action is enabled, the model still has to confirm it with you before running it:

* **Confirmation.** Every call, message, transfer, recording, purchase and account change needs your explicit approval (`confirm: true`), and your client also asks before running it.
* **Idempotency keys.** These prevent a retry from calling or texting twice.
* **Server limits.** Destination countries, call duration, calls and messages per minute and per hour, concurrency, a balance floor and a spending cap all apply, and each one can be configured.

<Warning>
  Calls and messages reach real people and are billed to your account. Enable these capabilities only for clients you trust, and keep the limits tight.
</Warning>

## What you can ask

| Ask | Tools the model uses |
| - | - |
| "What's my balance, and how many calls are live?" | `get_account_balance`, `get_concurrency`, `list_live_calls` |
| "Show yesterday's missed calls" | `list_call_records` with a date range and `hangup_cause` |
| "Call +919876543210 from my Bangalore number and read them this reminder" | `list_phone_numbers` → `make_call` → `speak_text` → `get_call_status` |
| "Build an IVR: press 1 for sales, 2 for support" | `get_vobiz_skill` (`vobiz-voice-xml`) → `generate_answer_xml` |
| "Text +14155550123 'Your order has shipped'" | `preview_message_cost` → `send_message` → `get_message` |
| "Who replied to our last broadcast?" | `list_broadcasts`, `list_messages` (`direction=in`), `list_conversations` |
| "Where do my webhooks go?" | `list_webhooks` |
| "Mute everyone except the host in the standup conference" | `get_conference` → `mute_conference_member` |
| "Stream this call to my agent at wss\://agent.example.com/ws" | `start_audio_stream` |
| "Create a sub-account for the Mumbai team and send them the KYC link" | `create_sub_account` → `create_sub_account_kyc_session` |

## Tools

| Toolset | Read-only | Actions (need confirmation) |
| - | - | - |
| `calls` | `get_call_status`, `list_live_calls` | `make_call`, `end_call`, `send_dtmf` |
| `call_control` | | `transfer_call`, `hold_call`, `unhold_call`, `play_audio`, `stop_audio`, `speak_text`, `stop_speaking`, `start_recording`, `stop_recording` |
| `conferences` | `list_conferences`, `get_conference` | `end_conference`, `end_all_conferences`, `mute_conference_member`, `unmute_conference_member`, `deafen_conference_member`, `undeafen_conference_member`, `kick_conference_member`, `hangup_conference_member`, `play_audio_to_conference_member`, `stop_audio_to_conference_member`, `start_conference_recording`, `stop_conference_recording` |
| `media` | `list_audio_streams`, `get_audio_stream`, `list_transactions`, `list_transaction_types` | `start_audio_stream`, `stop_audio_stream`, `delete_recording`, `release_phone_number`, `cancel_number_release`, `assign_number_to_subaccount`, `unassign_number_from_subaccount` |
| `records` | `get_call_details`, `list_call_records`, `get_call_recording`, `list_recordings` | |
| `voice_xml` | `generate_answer_xml`, `get_gather_result`, `list_webhook_events`, `list_webhooks` | `gather_dtmf` |
| `account` | `get_account_details`, `get_account_balance`, `get_concurrency`, `list_phone_numbers`, `get_phone_number_details`, `get_number_health`, `list_sip_trunks`, `get_sip_trunk` | |
| `provisioning` | `list_applications`, `get_application`, `search_available_numbers` | `create_application`, `update_application`, `delete_application`, `buy_phone_number`, `update_phone_number`, `create_sip_trunk`, `update_sip_trunk`, `delete_sip_trunk` |
| `sip` | `list_sip_endpoints`, `get_sip_endpoint`, `list_trunk_credentials`, `list_ip_acl_entries`, `list_origination_uris` | `create_sip_endpoint`, `update_sip_endpoint`, `delete_sip_endpoint`, `create_trunk_credential`, `update_trunk_credential`, `delete_trunk_credential`, `add_ip_acl_entry`, `update_ip_acl_entry`, `delete_ip_acl_entry`, `create_origination_uri`, `update_origination_uri`, `delete_origination_uri` |
| `subaccounts` | `list_sub_accounts`, `get_sub_account`, `get_sub_account_kyc_status` | `create_sub_account`, `update_sub_account`, `delete_sub_account`, `create_sub_account_kyc_session` |
| `messaging` | `list_messaging_numbers`, `preview_message_cost`, `list_messages`, `get_message`, `list_conversations`, `get_conversation_messages`, `list_broadcasts`, `get_broadcast`, `check_opt_out`, `list_opt_outs` | `send_message`, `add_opt_out`, `remove_opt_out` |
| `skills` | `list_vobiz_skills`, `get_vobiz_skill` | |

To load only some groups, set `VOBIZ_TOOLSETS`, for example `VOBIZ_TOOLSETS=calls,records,skills`. Set `VOBIZ_READ_ONLY=true` to keep only read-only tools. SIP passwords, credential secrets and sub-account tokens are always redacted; view or reset them in the console.

The hosted connector offers every tool except number purchases and the IVR tools that need a callback server of their own: `gather_dtmf`, `get_gather_result`, `list_webhook_events`, `hold_call` and `unhold_call`. Use the npm package in HTTP mode for those. The full input reference for every tool is in the [repository](https://github.com/vobiz-ai/Vobiz-MCP-Server/blob/main/docs/TOOLS.md).

## Skills, prompts and resources

The server bundles the [Vobiz Agent Skills](/docs/resources/skills) and exposes each one three ways:

* **Tools.** `list_vobiz_skills` and `get_vobiz_skill` work in every client.
* **Prompts.** Each skill is a prompt with an optional task. In Claude Code, type `/mcp__vobiz__vobiz-voice-xml build an IVR for a clinic`.
* **Resources.** `vobiz://skills/index` and `vobiz://skills/{name}`.

## Privacy

The server uses your Auth ID and Auth Token only to call the Vobiz API on your behalf. The hosted connector keeps no credential or conversation database, and logs never contain tokens, message text or phone numbers. It does not read your conversation history or files. See the [Vobiz privacy policy](https://www.vobiz.ai/privacy).

## Troubleshooting

| Symptom | Fix |
| - | - |
| `auth_failed` | Check your Auth ID and Auth Token in the console. For the hosted connector, disconnect and connect again. |
| `calls_disabled`, `messaging_disabled` or `provisioning_disabled` | Turn the capability on (see [Turn on actions](#turn-on-actions)). |
| `confirmation_required` | The model asks you first, then repeats the action with your approval. |
| `not_allowed` | The destination, sender or URL is outside the limits set for the server. The message says which setting applies. |
| `forbidden` on account details | Account details need main-account (`MA_`) credentials. Balance, numbers and calls work with sub-account keys. |
| `opted_out` on a message | The recipient opted out. Respect it; remove the opt-out only after they opt back in. |

## Related

<CardGroup cols={3}>
  <Card title="Vobiz Docs MCP server" icon="book-open" href="/docs/resources/mcp">
    Search the documentation from your AI client.
  </Card>

  <Card title="Agent Skills" icon="brain" href="/docs/resources/skills">
    Install the Vobiz skills into your coding agent.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Find and rotate your Auth ID and Auth Token.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.