Wavix MCP Server
A Model Context Protocol server that gives LLMs and AI agents direct access to the Wavix telecom platform — SMS/MMS, voice calls, 2FA, SIP trunking, phone-number management, 10DLC registration, call recordings, speech analytics, and billing.
Wavix is a global communications platform for sending SMS, placing voice calls, and running 2FA flows over a single API. A free trial is available; paid usage follows the Wavix pricing plan attached to your account.
The fastest way to use this MCP server is the hosted endpoint at https://mcp.wavix.com/mcp — point any MCP-compatible client at it and authenticate with your Wavix API key. If you need to self-host (custom Wavix deployment, behind a firewall, dedicated instance), see Run your own.
Table of contents
- Endpoint
- Install — one-click, Claude Code, Claude Desktop / Web, Cursor, VS Code, Codex CLI, Windsurf
- Run your own (self-host)
- Examples
- Tools → full catalogue in TOOLS.md
- Resources
- Authentication (best practices, if a token is compromised)
- Troubleshooting
- Compatibility & limits
- Support, Contributing, Security, License
Endpoint
| Field | Value |
|---|---|
| URL | https://mcp.wavix.com/mcp |
| Transport | Streamable HTTP |
| Auth | Authorization: Bearer <api_key> |
| Tools | see TOOLS.md |
| Resources | Wavix docs + OpenAPI spec (auto-discovered) |
Get a Wavix API key from the Wavix Console → Administration → API keys → Create new.
Install
Before you start: grab your Wavix API key.
- Sign in at https://wavix.com.
- Open Administration → API keys.
- Click Create new (or copy an existing key). Keep it handy — you'll paste it in place of
YOUR_API_KEYbelow.
One-click install
⚠️ The buttons below seed your editor's MCP config with a placeholder token
YOUR_API_KEY. After the editor finishes installing, open the generated config and replace the placeholder with your real API key before sending any request — otherwise every call will return401 Unauthorized.
To remove later: open the same config file (~/.cursor/mcp.json, .vscode/mcp.json, or the equivalent for your editor) and delete the wavix entry, or remove the connector through your editor's MCP / Connectors UI.
Claude Code
claude mcp add --transport http wavix https://mcp.wavix.com/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
Use claude mcp list to verify and /mcp inside a session for status.
Claude Desktop / Claude Web
Settings → Connectors → Add custom connector:
- Name:
Wavix - URL:
https://mcp.wavix.com/mcp - Transport:
Streamable HTTP - Authentication header:
Authorization: Bearer <api_key>
Cursor (manual)
Add to ~/.cursor/mcp.json (or project-level .cursor/mcp.json):
{
"mcpServers": {
"wavix": {
"url": "https://mcp.wavix.com/mcp",
"headers": {
"Authorization": "Bearer <api_key>"
}
}
}
}
Cursor 2.4+ exposes the full catalogue; earlier versions cap at 40.
VS Code (manual, GitHub Copilot Chat)
Create .vscode/mcp.json in your workspace (or add the same servers object under the "mcp" key in user settings.json):
{
"servers": {
"wavix": {
"type": "http",
"url": "https://mcp.wavix.com/mcp",
"headers": {
"Authorization": "Bearer <api_key>"
}
}
}
}
See the VS Code MCP servers guide for the up-to-date schema.
Codex CLI
Codex CLI supports MCP over stdio. Bridge to the hosted server via mcp-remote. Edit ~/.codex/config.toml:
[mcp_servers.wavix]
command = "npx"
args = [
"-y",
"mcp-remote",
"https://mcp.wavix.com/mcp",
"--header",
"Authorization:Bearer ${WAVIX_API_KEY}"
]
[mcp_servers.wavix.env]
WAVIX_API_KEY = "YOUR_API_KEY"
Windsurf / other clients
Any MCP client that supports Streamable HTTP transport with custom headers will work. Use:
- URL:
https://mcp.wavix.com/mcp - Header:
Authorization: Bearer <api_key>
Setting up via an AI agent? Point your agent at llms-install.md — it's a machine-readable install guide that gives the model the URL, header, and per-client configuration in a deterministic format so it doesn't improvise endpoint values.
Run your own
The hosted server works out of the box for most users. Self-host if you need to point at a non-public Wavix deployment, run behind a firewall, or operate inside your own infrastructure.
Docker
docker build -t wavix-mcp-server .
docker run --rm -p 8000:8000 wavix-mcp-server
The server listens on port 8000 and exposes the MCP endpoint at /mcp. Point your client at http://<host>:8000/mcp.
From source
git clone https://github.com/Wavix/wavix-mcp-server.git
cd wavix-mcp-server
pip install -e .
wavix-mcp
Requires Python 3.10+.
Configuration
| Env var | Default | Purpose |
|---|---|---|
WAVIX_API_BASE_URL | https://api.wavix.com | Override the upstream Wavix API endpoint (for internal deployments or staging) |
No Wavix credentials are required to run the server — they are forwarded per-request from the MCP client's Authorization: Bearer <api_key> header. Self-hosters are responsible for terminating TLS in front of the server (nginx, Caddy, cloud load balancer) before exposing it publicly.
Examples
Concrete prompts you can drop into any connected client.
Phone numbers below (
+1 310 555 0100,+44 7700 900123) are in reserved test ranges (NANP555and Ofcom070 09xx) — safe to copy verbatim, no real subscribers are reachable through them.
Send a transactional SMS
Prompt: "Send an SMS from +13105550100 to +447700900123 saying 'Your verification code is 4821'."
The agent calls sms_and_mms_messages_send with from, to, and text. Returns the message ID and delivery status.
Run a 2FA verification
Prompt: "Send a 2FA verification code to +13105550100 via SMS. When I give you the code I receive, check whether it's correct."
The agent calls two_fa_verification_create, waits for you to share the code that arrives via SMS, then calls two_fa_verification_check. Useful for prototyping passwordless flows without writing integration code.
Find and buy a phone number
Prompt: "Find an available US toll-free number with SMS capability, add it to my cart, and check out."
The agent chains buy_numbers_list (filtering by country and feature), cart_add, and cart_checkout. Confirm with the user before checkout — it charges the account.
Search call transcripts
Prompt: "Show me all inbound calls from yesterday longer than two minutes where the caller mentioned 'refund'."
The agent uses cdrs_search against transcriptions, then enriches each result via cdrs_get for full call metadata.
Pull a recording and transcribe it
Prompt: "Get the recording for call abc-123, ask Wavix to transcribe it, and return the transcription."
The agent calls call_recording_get (returns a pre-signed download URL), cdrs_retranscribe, then polls cdrs_transcription_get.
Audit billing
Prompt: "How much did we spend on SMS last month? Give me a download link for the most recent invoice PDF."
The agent calls billing_transactions_list filtered by type and date, then billing_invoices_list + billing_invoices_download. The download tool returns a pre-signed URL to the PDF, not the file itself — open the URL in a browser or pass it to your client to fetch the actual document.
Tools
<!-- tools:start -->122 tools, generated from the Wavix OpenAPI spec. Arguments mirror request parameters and body fields.
| Group | # | Coverage |
|---|---|---|
| SMS and MMS | 10 | Send, list, retrieve messages; sender IDs; opt-outs |
| Call control | 9 | Start / answer / end calls; play audio; collect DTMF |
| Call recording | 3 | List, download (pre-signed URL), delete |
| Call streaming | 2 | Start / stop media stream |
| Call webhooks | 3 | List, create, delete |
| CDRs | 6 | List, export, retrieve; transcription search and retranscribe |
| Speech Analytics | 4 | Upload, transcribe, retrieve original file |
| 2FA | 6 | Create / check / cancel / resend verification; events |
| My numbers | 7 | List, update, release; SMS / voice routing; document upload |
| Buy | 5 | Countries, regions, cities; available number search |
| Cart | 4 | Add, remove, retrieve, checkout |
| Number validator | 3 | Single and bulk validation |
| SIP trunks | 5 | Full CRUD |
| 10DLC | 30 | Brands, campaigns, vetting, evidence, event subscriptions |
| Profile | 3 | Get / update profile; account config |
| API Keys | 5 | List, create, activate / deactivate, delete |
| Sub-accounts | 5 | List, create, get, update; transactions |
| Billing | 3 | Transactions, invoices, statement download |
| Voice campaigns | 2 | Trigger and retrieve |
| Wavix Embeddable (WebRTC) | 5 | Widget tokens CRUD |
| Link shortener | 2 | Create short links; metrics |
See TOOLS.md for the complete tool list with one-line descriptions. The authoritative source is the Wavix OpenAPI spec — your client always sees the current live catalogue.
Resources
In addition to tools, the server exposes Wavix documentation as MCP Resources, so the model can pull authoritative context on demand instead of guessing from prior knowledge.
| URI scheme | Contents |
|---|---|
wavix://docs/<path> | Documentation pages from docs.wavix.com (auto-discovered via llms.txt). |
wavix://api/openapi.yaml | The full Wavix OpenAPI 3.0 specification. |
Both sources — docs.wavix.com and the Wavix OpenAPI spec — are publicly available and can be browsed directly without authentication.
Resources are fetched lazily on resources/read and cached server-side with a 1-hour TTL. The upstream Bearer token is never forwarded to documentation hosts — only to api.wavix.com.
Authentication
Every request from the client must include:
Authorization: Bearer <api_key>
The server forwards this header to api.wavix.com per-request. The token:
- is never logged,
- is never forwarded on cross-host redirects (e.g. pre-signed S3 download URLs),
- is never sent to documentation hosts.
If your client follows a pre-signed download URL returned by call_recording_get, billing_invoices_download, speech_analytics_file_get, or ten_dlc_brand_evidence_get, fetch it directly without the Authorization header.
Best practices
-
Use a dedicated API key for MCP. Create a separate API key at https://wavix.com → Administration → API keys (or via the
api_keys_createtool itself, from another session). This lets you revoke MCP access without disrupting other integrations. -
Rotate periodically. Treat the API key like any production secret: rotate on schedule and on any suspicion of leakage.
-
Keep API keys out of git. MCP client configs are easy to commit by accident, taking the token with them into history and CI logs. Most clients support
${env:VAR}substitution in the header value — store the API key in an env var or your OS keychain and reference it from the config. As a safety net, add the common client-config paths to your project's.gitignore:.cursor/mcp.json .vscode/mcp.json claude_desktop_config.json .claude/mcp.json .codex/config.toml
If a token is compromised
- In the Wavix Console, deactivate the key immediately (or call
api_keys_deactivate). - Create a replacement via
api_keys_createor the Console. - Update the client's config and reconnect.
- Review
billing_transactions_listandcdrs_listfor unexpected activity.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
401 Unauthorized from any tool | Missing or invalid Authorization: Bearer … header. Verify the API key is active in the Wavix Console. |
Tool returns a download_url, not the file itself | Expected. Recording, invoice, speech-analytics, and 10DLC evidence endpoints return pre-signed URLs (see Authentication). Fetch the URL directly without the Authorization header. |
| Client only shows ~40 tools, not the full catalogue | Older clients enforce a per-server tool cap. Upgrade (Cursor 2.4+, latest VS Code, latest Claude). |
Tool not found for a tool listed in this README | The local client may be caching an old tool list. Restart the client, or remove and re-add the server. |
4xx with an errors array | Validation error from Wavix API. Inspect errors; cross-reference the relevant wavix://docs/* page or the OpenAPI spec. |
| Cannot reach the server | Confirm DNS and outbound HTTPS to mcp.wavix.com:443. |
| Agent calls a destructive tool unexpectedly | Most clients can require confirmation before tool calls — enable that setting and rotate to a dedicated MCP API key (see Best practices). |
Compatibility & limits
- Compatible with any MCP client supporting Streamable HTTP transport (Claude Desktop / Web / Code, Cursor 2.4+, VS Code, Windsurf, custom MCP SDKs) and any agent framework with an MCP client adapter.
- Older clients may enforce a per-server tool cap; upgrade to a recent version to access the full catalogue.
- Rate limits and usage charges follow your Wavix account plan. See Wavix pricing.
Changelog
The hosted server is updated continuously as the Wavix OpenAPI spec evolves; new tools appear automatically and existing tool arguments may gain optional fields. Documentation changes for this repository are tracked under Releases. For substantial behavior changes affecting tool inputs or auth, we will publish a notice both there and in the Wavix release notes.
Support
- Product docs: https://docs.wavix.com
- API reference: https://docs.wavix.com/api-reference
- Questions / feedback: support@wavix.com
Contributing
This repository is source-available but not open to external contributions. Pull requests are auto-closed, and Issues / Discussions are disabled. Send bug reports, feature requests, and feedback to support@wavix.com. See CONTRIBUTING.md for details.
If you find a bug in the underlying FastMCP framework, please report it upstream there.
Security
To report a security vulnerability, please email support@wavix.com with the subject Security: <short summary> rather than opening a public issue. See SECURITY.md for details.
License
MIT © Wavix