Wixzel Voice

wixzel-voice-mcp

Wixzel Voice for AI agents. A Model Context Protocol server that lets Claude Code, claude.ai, Claude Desktop, Cursor, and any other MCP client create voice agents, connect a carrier, place calls, run campaigns, and read what it all cost, using the Wixzel Voice API.

Wixzel Voice: APIs for AI voice agents. One API key, one balance, every voice engine.

One tool per API operation, 56 in all, each annotated so a client knows which are read-only, which delete, and which spend money or make a real phone ring. Three prompts (quickstart, diagnose_call, spend_report) package the common workflows.

Published as wixzel-phone-mcp up to 0.3.0, while the product was briefly called Wixzel Phone. Those releases keep working: api.phone.wixzel.com and mcp.phone.wixzel.com keep serving.

Two ways to run it:

The console's AI clients page at voice.wixzel.com/connect generates every command below with a key filled in.

Claude Code

# hosted: sign in with your Wixzel account when Claude Code asks (/mcp → Authenticate)

claude mcp add --transport http wixzel-voice https://mcp.voice.wixzel.com/mcp

local: a scoped key from the console

claude mcp add wixzel-voice -e WIXZEL_API_KEY=wv_live_... -- npx -y wixzel-voice-mcp

Or commit a .mcp.json so every collaborator gets it:

{

"mcpServers": { "wixzel-voice": { "command": "npx", "args": ["-y", "wixzel-voice-mcp"], "env": { "WIXZEL_API_KEY": "${WIXZEL_API_KEY}" } } } }

Then:

/mcp__wixzel-voice__quickstart

claude.ai and Claude Desktop

Settings → Connectors → Add custom connector → https://mcp.voice.wixzel.com/mcp → Connect. You sign in to the console, tick what the client may do, and it receives a scoped key of its own. Disconnect it from the console's AI clients page at any time.

Cursor, Windsurf, VS Code, others

Same shape as .mcp.json above: command npx, args ["-y", "wixzel-voice-mcp"], env WIXZEL_API_KEY. Clients that connect over HTTP but cannot do OAuth send the key as Authorization: Bearer wv_live_....

What the agent can do

Prompts: quickstart (connect a carrier, register a number, build an agent, place a first call), diagnose_call (why did call X fail), spend_report (what did this month cost, and where).

Resources: wixzel://guide (the operating guide the server also sends as its instructions) and wixzel://connection (base URL and whether the key is live or test; never the key itself).

How it keeps the agent honest

• Money is explicit. place_call, start_campaign, create_topup and create_voice_clone are annotated openWorldHint: true and their descriptions tell the model to confirm with the user first. Clients that gate on annotations will ask before running them.
• Idempotency is automatic. The two money paths require an Idempotency-Key; the server generates one per call and accepts an explicit idempotency_key for deliberate retries, so a network timeout never turns into two calls.
• Errors are actionable. Every failure returns the API's machine-readable code, the request_id, and a hint that says what to do: which scope is missing, that the balance is short, that a cursor was mangled.
• Rate limits are absorbed. A 429 is retried after Retry-After up to twice before the model sees it. Those requests are never charged.
• Scopes do the gating. The key decides what works. There is no admin scope, and a key cannot create one broader than itself.
• Secrets stay put. SIP passwords are write-only; API key secrets appear once, in the tool result, and nowhere else. The key this server runs with is never exposed through any tool or resource.

Running the hosted mode yourself

npx wixzel-voice-mcp --http 3939

Each request's bearer becomes the API key for a fresh, throwaway MCP server; nothing is shared between requests. A request without a bearer gets a 401 with WWW-Authenticate: Bearer resource_metadata="…", and /.well-known/oauth-protected-resource names the API as the authorization server, which is how connectors discover sign-in on their own. GET /healthz reports liveness.

Development

The source is mirrored at wixzel-voice-sdks; it is developed in the private monorepo that also holds the API, so a change to an endpoint and the change to its tool land together.

npm install                # at the repo root

npm test -w apps/mcp # offline: a fake API behind in-memory and HTTP transports, plus a spec-coverage check npm run build -w apps/mcp npm run inspect -w apps/mcp # MCP Inspector against the built server

Tool schemas are hand-written zod. The spec-coverage test compares them against the API's OpenAPI document (docs/openapi.json) in both directions, so an endpoint added to the API fails the build here until it gets a tool.

Not for application code

This server is for AI agents. Application code should use the SDKs: wixzel-voice on npm and wixzel_voice on pub.dev.

License

MIT. Wixzel Voice itself is a hosted service; see voice.wixzel.com for terms.