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

# Wavix MCP server

> Connect any MCP-compatible AI client to your Wavix account with OAuth 2.1 or an API key, and manage SMS, voice, numbers, and billing through natural language.

The **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** is an open standard for connecting AI assistants to external tools and services. The **Wavix MCP server** exposes your Wavix account as tools any MCP-compatible client can call: SMS, voice, numbers, SIP trunking, 2FA, speech analytics, and billing.

```http theme={null}
https://mcp.wavix.com/mcp
```

## When to use MCP vs. the REST API

| | MCP | REST API |
| - | - | - |
| **Best for** | AI-assisted workflows, exploration, prototyping | Production applications, automation pipelines |
| **How you interact** | Natural language prompts | Code (HTTP requests, SDK calls) |
| **Who uses it** | Developers, operations teams, AI agents | Backend services, scheduled jobs |

## How you authorize

Two credentials work, both fully supported. Neither is scheduled for removal.

| | OAuth 2.1 | API key |
| - | - | - |
| **How you connect** | Approve a consent screen in the browser | Paste a Bearer token into your client's config |
| **Client stores** | A 15-minute token plus a rotating refresh token | A long-lived secret, in plain text |
| **Identifies** | The Wavix user who approved it | The Wavix account the key belongs to |
| **Permissions** | Chosen per group, re-checked on every request | Fixed when you create the key |
| **Revoking** | **Connected apps** in the Wavix portal, immediate | Delete the key in the Wavix portal |

Use OAuth where your client supports it: no long-lived secret on disk, per-group permissions, self-service revocation. Use an API key everywhere else — it works with every MCP client, carries most MCP traffic today, and suits CI, where nobody is present to approve a consent screen.

For the OAuth path you only need to sign in to your Wavix account in a browser. For the API-key path, create a key under **Administration** → **API Keys** in the Wavix portal — see [Authentication](/api-reference/authentication) — and substitute it for `YOUR_API_KEY` below.

<Note>
  OAuth support varies by client. Claude Code runs the flow natively and is verified against the Wavix authorization server. For Cursor, VS Code, and Codex, the API-key configuration below is the documented path.
</Note>

## Connect a client

<Tabs>
  <Tab title="Claude Code">
    **OAuth — recommended.** Add the server with no credentials:

    ```bash theme={null}
    claude mcp add wavix https://mcp.wavix.com/mcp
    ```

    Claude Code discovers the authorization server, registers itself, and opens your browser so you can grant permissions.

    **API key.** Pass the key as an `Authorization` header instead:

    ```bash theme={null}
    claude mcp add wavix https://mcp.wavix.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    Because a header is supplied, Claude Code uses it as-is and doesn't start the OAuth flow.

    Either way, confirm the result:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Cursor">
    Open the command palette with <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> on Windows), search for **Open MCP settings**, and select **Add custom MCP** to open `mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "wavix": {
          "url": "https://mcp.wavix.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Create `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "servers": {
        "wavix": {
          "type": "http",
          "url": "https://mcp.wavix.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Open (or create) `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.wavix]
    url = "https://mcp.wavix.com/mcp"
    http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
    ```
  </Tab>
</Tabs>

Any other client that speaks streamable HTTP can connect too. Send a Wavix API key as a Bearer token, or implement the flow described in [Authorization](/mcp/authorization).

## Granting permissions

Every OAuth client sends you to the same consent screen at `app.wavix.com`. It is the only part of the flow you interact with, and what you choose there decides what the agent can do.

<Steps>
  <Step title="Check who you are authorizing, and as whom">
    The heading names the application requesting access. Below it, the screen shows the Wavix user you are signed in as — the grant is recorded against **that user**, so use **Switch account** if it is the wrong one.

    A logo appears only when the application serves it over HTTPS from the same host as its redirect URL. Treat a missing logo as normal, not as a warning sign.
  </Step>

  <Step title="Set a level for each section">
    **Requested access** summarizes what the client asked for, as a count of write and read permissions. Below it, permissions are grouped into five sections. Expand one to set its capabilities individually.

    | Section | Capabilities |
    | - | - |
    | Messaging | Messages, Campaigns, 2FA |
    | Voice | Calls, Trunks, Recordings |
    | Numbers | Numbers, Validator |
    | Account and billing | Billing, Account, Subaccounts |
    | Developer | Webhooks, Embeddable |

    Each carries a **No access**, **Read**, or **Write** selector, pre-set to what the client requested. **Your job here is to narrow it**, not to opt in — anything you leave alone is granted as asked.

    Sections your role does not permit are not shown at all. If you expected one and it is missing, your Wavix role lacks that permission.
  </Step>

  <Step title="Read the write warning, if it appears">
    Selecting **Write** anywhere raises a warning: write access lets the application send messages, make calls, and buy numbers using your account balance. These actions are immediate and billable.
  </Step>

  <Step title="Authorize or cancel">
    **Authorize** completes the connection and returns you to the client. **Cancel** grants nothing.

    **Authorize** stays disabled while every section is set to **No access** — a grant has to carry at least one permission.
  </Step>
</Steps>

## Example prompts

* **"The SMS I sent to +12125551234 an hour ago hasn't been delivered. Can you check what happened?"** — finds the message with `sms_and_mms_messages_list`, then reads its delivery status and error codes.
* **"Show me all outbound calls from yesterday that weren't answered."** — queries `cdrs_search` by date, direction, and disposition.
* **"Search last month's inbound calls for 'refund' or 'escalate.' Show me the call UUIDs."** — scans transcriptions through `cdrs_search`.
* **"Find available US local numbers containing '555' and buy the first one."** — searches with `buy_numbers_list` and adds to the cart, asking you to confirm before checkout.
* **"What's my current balance, and is it enough for 10,000 SMS to US numbers?"** — totals recent activity from `billing_transactions_list` and estimates the send.

## What an OAuth grant binds

* **One Wavix user, not an account.** The grant belongs to whoever approved the consent screen.
* **No API key is created.** Nothing new is minted, stored, or exposed to leak or rotate.
* **Permissions are re-checked on every request.** Granted scopes are intersected with the user's *current* permissions, so removing one takes effect on the next call.
* **Revocation is immediate.** Revoking under **Connected apps** stops the next request; you don't wait for a token to expire.
* **Losing access revokes the grants.** Blocking or suspending a user, or removing their account level, revokes every grant they created.

### Sub-accounts

Each sub-account authorizes independently, under its own user and its own permissions — even though its access level, plan, and blocked state come from the master account. A manager (the master account, or a sub-account whose role is **Admin**) sees and revokes every grant across the account.

<Warning>
  **There is no organization-level or admin-level consent.** An administrator cannot pre-approve a connector for everyone, and cannot approve one on another user's behalf. Every user authorizes for themselves. A permission the user's role forbids is blocked at the consent screen, not routed to an administrator.
</Warning>

## When a tool is missing or fails

Under OAuth, **a tool outside your granted permissions is omitted from the tool list entirely** — not listed and then refused.

Choose **No access** for **Numbers** at the consent screen and your agent never learns that number search exists. Asked to buy a number, it reports having no tool for the job, not that you lack permission. To widen a grant, revoke it under **Connected apps** and connect again.

Every tool and the permission it needs is listed in the [tool catalogue](/mcp/tools).

Three related cases:

* **The `api_keys_*` tools are never available over OAuth.** They are hidden from every OAuth connection by design: a delegated grant must never mint or manage your account's API keys. Connect with an API key if you need them.
* **A tool is listed but the call is refused.** Your client is working from a stale tool list. Restart it so it re-reads the catalogue.
* **API-key connections aren't filtered.** They see the full catalogue, and the Wavix API enforces that key's own scopes. A `401` on every call means the key itself is inactive, deleted, or mistyped — check it under **Administration** → **API Keys** in the Wavix portal.

## Review and revoke access

**OAuth grants** — go to **My Account** → **Connected apps** in the Wavix portal and revoke the application. Revocation takes effect on the connector's next request. Any user manages their own grants; the master account and any sub-account whose role is **Admin** manages every grant across the account. To change granted permissions, revoke and connect again.

**API keys** — go to **Administration** → **API Keys** and delete the key. This breaks every integration using it, so give MCP a dedicated restricted key.

## Recommendations

* **Grant only what the agent needs.** Set every unused section to **No access**. With an API key, create a dedicated restricted key: a key scoped to `messages` doesn't need SIP trunks or number purchasing.
* **Review your grants.** **Connected apps** in the Wavix portal lists everything with access to your account and revokes it in one click.
* **Some actions are immediate and billable.** The agent confirms before purchasing numbers, but sends messages and places calls without a follow-up prompt.
* **Don't put it behind a customer-facing agent.** A connected agent acts with your account's authority and balance, so anything it can be talked into doing, it does for real. Keep MCP connections to agents your own team operates.

The Wavix MCP server is open source — [browse the code, file issues, or contribute on GitHub](https://github.com/Wavix/wavix-mcp-server).


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