# Wavix MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-supported-blue.svg)](https://modelcontextprotocol.io)

A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://wavix.com) is a global communications platform for sending SMS, placing voice calls, and running 2FA flows over a single API. A [free trial](https://wavix.com) is available; paid usage follows the Wavix [pricing](https://wavix.com/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](#run-your-own).

## Table of contents

- [Endpoint](#endpoint)
- [Install](#install) — [sign in with an account](#sign-in-with-a-wavix-account), [API key](#connect-with-an-api-key), [one-click](#one-click-install), [Claude Code](#claude-code), [Claude Desktop / Web](#claude-desktop--claude-web), [Cursor](#cursor-manual), [VS Code](#vs-code-manual-github-copilot-chat), [Codex CLI](#codex-cli), [Windsurf](#windsurf--other-clients)
- [Run your own](#run-your-own) (self-host)
- [Examples](#examples)
- [Tools](#tools) → [full catalogue in TOOLS.md](TOOLS.md)
- [Resources](#resources)
- [Authentication](#authentication) ([best practices](#best-practices), [if a token is compromised](#if-a-token-is-compromised))
- [Troubleshooting](#troubleshooting)
- [Compatibility & limits](#compatibility--limits)
- [Support](#support), [Contributing](#contributing), [Security](#security), [License](#license)

## Endpoint

| Field | Value |
| --- | --- |
| URL | `https://mcp.wavix.com/mcp` |
| Transport | Streamable HTTP |
| Auth | Sign in with a Wavix account (OAuth 2.1), **or** `Authorization: Bearer <api_key>` |
| Tools | see [TOOLS.md](TOOLS.md) |
| Resources | Wavix docs + OpenAPI spec (auto-discovered) |

Get a Wavix API key from the [Wavix Console](https://wavix.com) → **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](#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`.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22wavix%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//mcp.wavix.com/mcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20YOUR_API_KEY%22%7D%7D)
[![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=wavix&config=eyJ1cmwiOiJodHRwczovL21jcC53YXZpeC5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfQVBJX0tFWSJ9fQ==)

**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

```bash
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`):

```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`):

```json
{
  "servers": {
    "wavix": {
      "type": "http",
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}
```

See the [VS Code MCP servers guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for the up-to-date schema.

### Codex CLI

Codex CLI supports MCP over stdio. Bridge to the hosted server via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Edit `~/.codex/config.toml`:

```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`](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

```bash
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

```bash
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) |
| `OAUTH_ISSUER` | unset | Base URL of the OAuth 2.1 authorization server. Its JWKS is read from `<issuer>/.well-known/jwks.json` |
| `OAUTH_RESOURCE` | unset | Public base URL this server is reached at, used as the resource identifier |
| `OAUTH_API_KEY_PASSTHROUGH` | `true` | With OAuth on, still accept a bearer that is not an OAuth JWT and forward it upstream (API keys keep working). Set `false` to require a JWT |
| `MCP_PATH` | `/mcp` | Path the MCP endpoint is served on |

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.

Leaving either of `OAUTH_ISSUER` / `OAUTH_RESOURCE` unset keeps the previous
behaviour: no metadata is published and whatever bearer token the client sends
is forwarded upstream unverified.

[rfc9728]: https://datatracker.ietf.org/doc/html/rfc9728
[rfc8707]: https://datatracker.ietf.org/doc/html/rfc8707

## 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 (NANP `555` and Ofcom `070 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_by_call` (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, and what invoices were issued?"

The agent calls `billing_transactions_list` filtered by type and date, then `billing_invoices_list`. Downloading the invoice PDF itself is not exposed over MCP — fetch it from the Wavix API or dashboard.

## Tools

<!-- tools:start -->
116 tools, generated from the [Wavix OpenAPI spec](https://github.com/Wavix/wavix-openapi). Arguments mirror request parameters and body fields.

| Group | # | Coverage |
| --- | ---: | --- |
| [SMS and MMS](TOOLS.md#sms-and-mms) | 9 | Send, list, retrieve messages; sender IDs; opt-outs |
| [Call control](TOOLS.md#call-control) | 9 | Start / answer / end calls; play audio; collect DTMF |
| [Call recording](TOOLS.md#call-recording) | 4 | List, download (pre-signed URL), delete |
| [Call streaming](TOOLS.md#call-streaming) | 2 | Start / stop media stream |
| [Call webhooks](TOOLS.md#call-webhooks) | 3 | List, create, delete |
| [CDRs](TOOLS.md#cdrs) | 6 | List, retrieve; transcription search and retranscribe |
| [Speech Analytics](TOOLS.md#speech-analytics) | 3 | Transcribe, retrieve original file |
| [2FA](TOOLS.md#2fa) | 6 | Create / check / cancel / resend verification; events |
| [My numbers](TOOLS.md#my-numbers) | 5 | List, update, release; SMS / voice routing |
| [Buy](TOOLS.md#buy) | 5 | Countries, regions, cities; available number search |
| [Cart](TOOLS.md#cart) | 4 | Add, remove, retrieve, checkout |
| [Number validator](TOOLS.md#number-validator) | 3 | Single and bulk validation |
| [SIP trunks](TOOLS.md#sip-trunks) | 5 | Full CRUD |
| [10DLC](TOOLS.md#10dlc) | 29 | Brands, campaigns, vetting, evidence, event subscriptions |
| [Profile](TOOLS.md#profile) | 3 | Get / update profile; account config |
| [API Keys](TOOLS.md#api-keys) | 4 | List, create, update, delete |
| [Sub-accounts](TOOLS.md#sub-accounts) | 5 | List, create, get, update; transactions |
| [Billing](TOOLS.md#billing) | 2 | Transactions; list invoices / statements |
| [Voice campaigns](TOOLS.md#voice-campaigns) | 2 | Trigger and retrieve |
| [Wavix Embeddable (WebRTC)](TOOLS.md#wavix-embeddable-webrtc) | 5 | Widget tokens CRUD |
| [Link shortener](TOOLS.md#link-shortener) | 2 | Create short links; metrics |

<!-- tools:end -->

See **[TOOLS.md](TOOLS.md)** for the complete tool list with one-line descriptions. The authoritative source is the [Wavix OpenAPI spec](https://github.com/Wavix/wavix-openapi) — 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](https://docs.wavix.com) (auto-discovered via [`llms.txt`](https://llmstxt.org/)). |
| `wavix://api/openapi.yaml` | The full Wavix OpenAPI 3.0 specification. |

Both sources — [docs.wavix.com](https://docs.wavix.com) and the [Wavix OpenAPI spec](https://github.com/Wavix/wavix-openapi) — 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

The hosted server accepts two connection methods — neither is preferred:

- **Sign in with a Wavix account (OAuth 2.1).** For OAuth-capable clients. The client runs the authorization flow and the user signs in; no API key is stored. Access is scope-limited to what the user approves and their account role permits. See [Sign in with a Wavix account](#sign-in-with-a-wavix-account).
- **Wavix API key (Bearer).** For any Streamable-HTTP client. Every request 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_by_call`, `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_create` tool 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`:

  ```gitignore
  .cursor/mcp.json
  .vscode/mcp.json
  claude_desktop_config.json
  .claude/mcp.json
  .codex/config.toml
  ```

### If a credential is compromised

**If you connected with an API key:**

1. In the Wavix Console, deactivate or delete that key immediately (or call `api_keys_delete`).
2. Create a replacement via `api_keys_create` or the Console.
3. Update the client's config and reconnect.

**If you connected by signing in with your Wavix account:**

1. Revoke the connection from the Wavix portal's grant-management page, which lists the connections you authorized and revokes the one you choose — this invalidates that connection's tokens. No API key is involved.
2. Reconnect and sign in again.

In either case, review `billing_transactions_list` and `cdrs_list` for unexpected activity.

## Troubleshooting

| Symptom | Likely cause / fix |
| --- | --- |
| `401 Unauthorized` from any tool | Authentication failed. With an API key: the `Authorization: Bearer …` header is missing, or the key is invalid or inactive — verify it in the Wavix Console. With account sign-in: your session/token expired or was revoked, or sign-in never completed — reconnect and sign in again. |
| Tool returns a `download_url`, not the file itself | Expected. Recording, speech-analytics, and 10DLC evidence endpoints return pre-signed URLs (see [Authentication](#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). |
| Fewer tools available after signing in with a Wavix account | Expected. Account sign-in is scope-filtered — you get the tools your approved scopes and account role allow, not the full catalogue. An API-key connection sees the full tool surface. To widen the set, approve more scopes at sign-in (subject to your role) or connect with an API key that carries them. |
| `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](#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](https://wavix.com/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](https://github.com/Wavix/wavix-mcp-server/releases). For substantial behavior changes affecting tool inputs or auth, we will publish a notice both there and in the [Wavix release notes](https://docs.wavix.com/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`](CONTRIBUTING.md) for details.

If you find a bug in the underlying [FastMCP](https://github.com/jlowin/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`](SECURITY.md) for details.

## License

[MIT](LICENSE) © Wavix