Wavix MCP server - Wavix Docs

The Model Context Protocol (MCP) 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.

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) and substitute it for YOUR_API_KEY below.

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.

Connect a client

Claude Code
Cursor
VS Code
Codex

OAuth (recommended). Add the server with no credentials:

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:

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:

claude mcp list

Open the command palette with Cmd+Shift+P (Ctrl+Shift+P on Windows), search for Open MCP settings, and select Add custom MCP to open mcp.json:

{
  "mcpServers": {
    "wavix": {
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Create .vscode/mcp.json in your project:

{
  "servers": {
    "wavix": {
      "type": "http",
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Open (or create) ~/.codex/config.toml:

[mcp_servers.wavix]
url = "https://mcp.wavix.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

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.

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.

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.

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.

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.

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, because a grant has to carry at least one permission.

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.

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.

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 catalog. 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 catalog.
API-key connections aren’t filtered. They see the full catalog, 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.

Messaging

Two-factor authentication

Voice

Numbers

MCP server

​When to use MCP vs. the REST API

​How you authorize

​Connect a client

​Granting permissions

​Example prompts

​What an OAuth grant binds

​Sub-accounts

​When a tool is missing or fails

​Review and revoke access

​Recommendations

When to use MCP vs. the REST API

How you authorize

Connect a client

Granting permissions

Example prompts

What an OAuth grant binds

Sub-accounts

When a tool is missing or fails

Review and revoke access

Recommendations