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 connect by signing in with your Wavix account or with a 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 — sign in with an account, API key, 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

Get a Wavix API key from the Wavix Console → Administration → API keys → Create new.

Install

Two ways to connect — pick whichever your client supports; neither is required over the other.

Sign in with a Wavix account

If your MCP client supports OAuth (Claude Desktop / Web, and other OAuth-capable clients), connect without an API key: add the connector for https://mcp.wavix.com/mcp and, when the client prompts, sign in with your Wavix account and approve access. The client runs the OAuth 2.1 flow and stores the token itself — nothing to paste. The tools you get are scoped to what you approve and your account role permits (see Troubleshooting).

Connect with an API key

Before you start: grab your Wavix API key.

1. Sign in at https://wavix.com.
2. Open Administration → API keys.
3. Click Create new (or copy an existing key). Keep it handy — you'll paste it in place of YOUR_API_KEY below.

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 return 401 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>

To connect by signing in instead, add the connector without an authentication header and sign in with your Wavix account when the client prompts.

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

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.

OAuth 2.1 (optional)

Set OAUTH_ISSUER and OAUTH_RESOURCE together to turn the server into an OAuth 2.1 protected resource. It then publishes [RFC 9728][rfc9728] metadata at /.well-known/oauth-protected-resource<MCP_PATH>, validates incoming access tokens as JWTs against the issuer's JWKS, and answers unauthenticated requests with a WWW-Authenticate challenge pointing at that metadata. MCP clients that support OAuth use this to run the authorization flow themselves, so users no longer paste an API key into their client config.

The audience each token must carry is OAUTH_RESOURCE + MCP_PATH, which is also the resource value published in the metadata. Authorization servers implementing [RFC 8707][rfc8707] compare the client's resource parameter against that string exactly, so the two must be configured to match — including the path.

Enabling OAuth does not cut off clients that authenticate with a Wavix API key. A bearer token that is not a valid OAuth JWT is forwarded upstream unverified, exactly as before, leaving the Wavix API the sole authority on it — so an existing deployment can turn OAuth on for new clients without breaking the ones already connected. A request carrying no token at all still gets the WWW-Authenticate challenge, which is what lets an OAuth-capable client discover the authorization server. Only OAuth-authenticated connections are scope-filtered; an API-key connection sees the full tool surface.

Set OAUTH_API_KEY_PASSTHROUGH=false to drop that fallback and require a valid JWT — the strict mode to switch to once API-key access is retired.