wixzel-voice-mcp 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 0.4.0 (2026-09-29)
+
+Renamed from `wixzel-phone-mcp` to `wixzel-voice-mcp`, because the product is
+called Wixzel Voice again. The tools and prompts are unchanged.
+
+- Install and run `wixzel-voice-mcp` (`npx -y wixzel-voice-mcp`); the binary is
+  `wixzel-voice-mcp` too. The server advertises itself as `wixzel-voice`, and
+  the examples add it under that name, so its prompts appear as
+  `/mcp__wixzel-voice__quickstart`. A connection already added as
+  `wixzel-phone` keeps the name it was given.
+- The default API base URL is now `https://api.voice.wixzel.com`, and the
+  hosted server is `https://mcp.voice.wixzel.com/mcp`.
+  `https://api.phone.wixzel.com` and `https://mcp.phone.wixzel.com/mcp` keep
+  serving, so `wixzel-phone-mcp` 0.3.0 and earlier, and connectors added with
+  the old address, keep working without a change.
+- In HTTP mode on the hosted names, the protected-resource metadata and the
+  `401` challenge name the host the client connected to. MCP clients refuse
+  metadata for another origin, so this is what keeps a connector added as
+  `mcp.phone.wixzel.com` able to sign in again.
+- Requests send `User-Agent: wixzel-voice-mcp/0.4.0`. It said `0.2.1` through
+  the 0.3.0 release; it now follows the package version.
+- The operating guide the server sends as its instructions describes Wixzel
+  Voice as the API and MCP server people build agents with, not as the agents.
+- Carries what the official MCP Registry needs to list it as
+  `com.wixzel/voice`: `mcpName` in `package.json`, and `server.json` in the
+  source.
+
+## 0.3.0
+
+`create_realtime_session`: mint a one-minute, single-use client secret so a
+web page or app can talk to an agent over `wss /v1/realtime`, with no SIP
+trunk. Annotated as a write, not a spend — minting charges nothing; the
+session bills when a client connects. 65 tools.
+
+## 0.2.2
+
+Five webhook tools: `get_webhook`, `update_webhook`, `rotate_webhook_secret`,
+`test_webhook` and `list_webhook_deliveries`. The `webhooks:read` and
+`webhooks:write` scopes were already in the scope list and reached nothing;
+they now reach a real resource. 64 tools.
+
+`test_webhook` is annotated as reaching the outside world — it POSTs to a
+third-party endpoint — but it spends no credit.
+
+## 0.2.1
+
+Point `repository` at the public mirror, github.com/aqeelshamz/wixzel-phone-sdks. The 0.2.0 metadata named the private monorepo, so the link on the npm page did not resolve. No code changes.
+
+## 0.2.0
+
+Moved into the monorepo, added Streamable HTTP mode with OAuth discovery, protected-resource metadata and a token probe.
+
+## 0.1.0
+
+First release: 56 tools, three prompts, two resources, over stdio.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wixzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# wixzel-voice-mcp
+
+[![npm](https://img.shields.io/npm/v/wixzel-voice-mcp?style=flat-square&logo=npm&logoColor=white&label=npm&color=A0D425&labelColor=0D0D0D)](https://www.npmjs.com/package/wixzel-voice-mcp)
+[![MIT](https://img.shields.io/badge/licence-MIT-A0D425?style=flat-square&labelColor=0D0D0D)](LICENSE)
+**Wixzel Voice for AI agents.** A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://voice.wixzel.com) 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:
+
+| | Where | Auth |
+|---|---|---|
+| **Hosted**, `https://mcp.voice.wixzel.com/mcp` | Wixzel's servers | OAuth sign-in from the client, or a bearer key |
+| **Local**, `npx -y wixzel-voice-mcp` | Your machine, stdio | `WIXZEL_API_KEY` in the environment |
+
+The console's **AI clients** page at [voice.wixzel.com/connect](https://voice.wixzel.com/connect) generates every command below with a key filled in.
+
+## Claude Code
+
+```bash
+# 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:
+
+```json
+{
+  "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
+
+| Family | Tools |
+|---|---|
+| Engines | `list_engines` |
+| Agents | `list_agents` `get_agent` `create_agent` `update_agent` `delete_agent` |
+| Calls | `place_call` `list_calls` `get_call` `get_call_transcript` `hangup_call` `delete_call` |
+| SIP trunks | `list_sip_trunks` `get_sip_trunk` `create_sip_trunk` `update_sip_trunk` `delete_sip_trunk` `check_sip_trunk_status` `test_sip_trunk` `get_sip_trunk_logs` |
+| Phone numbers | `list_phone_numbers` `get_phone_number` `create_phone_number` `update_phone_number` `delete_phone_number` |
+| Leads | `list_leads` `get_lead` `create_lead` `update_lead` `delete_lead` `import_leads` |
+| Campaigns | `list_campaigns` `get_campaign` `create_campaign` `start_campaign` `pause_campaign` `delete_campaign` |
+| Knowledge bases | `list_knowledge_bases` `get_knowledge_base` `create_knowledge_base` `update_knowledge_base` `delete_knowledge_base` |
+| Appointments | `list_appointments` `get_appointment` `create_appointment` `update_appointment` `delete_appointment` |
+| Billing & usage | `get_balance` `list_ledger_entries` `create_topup` `get_usage_summary` `list_usage_events` |
+| API keys | `list_api_keys` `create_api_key` `rotate_api_key` `revoke_api_key` |
+
+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` and `create_topup` 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
+
+```bash
+npx wixzel-voice-mcp --http 3939
+```
+
+| Variable | Purpose |
+|---|---|
+| `MCP_PORT` | Port. Default 3939; `--http <port>` overrides. |
+| `MCP_BIND` | Interface. Default `127.0.0.1`; terminate TLS in front rather than binding wider. |
+| `MCP_PUBLIC_URL` | The URL clients use, e.g. `https://mcp.voice.wixzel.com/mcp`. Advertised as the OAuth resource. |
+| `WIXZEL_API_BASE_URL` | The API, which is also the OAuth authorization server. Default `https://api.voice.wixzel.com`. |
+| `WIXZEL_API_VERSION` | Optional `Wixzel-Version` date pin. |
+| `WIXZEL_API_KEY` | Stdio mode: the key. HTTP mode: a fallback for requests without a bearer, **accepted only when `MCP_PUBLIC_URL` is a loopback address**. |
+
+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](https://github.com/aqeelshamz/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.
+
+```bash
+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`](https://www.npmjs.com/package/wixzel-voice) on npm and
+[`wixzel_voice`](https://pub.dev/packages/wixzel_voice) on pub.dev.
+
+## License
+
+MIT. Wixzel Voice itself is a hosted service; see [voice.wixzel.com](https://voice.wixzel.com) for terms.

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A small HTTP client for the Wixzel Voice API.
+ *
+ * Deliberately dependency-free: `fetch` is built into Node 20+, and the API's
+ * conventions (bearer key, JSON, structured errors with a request_id, cursor
+ * pagination, Idempotency-Key on money paths) are simple enough that a wrapper
+ * around fetch is the whole client.
+ */
+/**
+ * api.phone.wixzel.com, the default before 0.4.0, keeps serving the same API,
+ * so older releases of this package keep working.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.voice.wixzel.com";
+export declare const USER_AGENT = "wixzel-voice-mcp/0.4.0";
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export type QueryValue = string | number | boolean | null | undefined;
+export interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    /** Sent as `Idempotency-Key`. Generated when `idempotent` is true and none is given. */
+    idempotencyKey?: string;
+    idempotent?: boolean;
+}
+export interface WixzelErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param?: string | null;
+    request_id?: string;
+}
+/** Everything a caller needs to act on a failed request, in one object. */
+export declare class WixzelApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | null;
+    readonly requestId: string | null;
+    readonly retryAfterSeconds: number | null;
+    readonly balanceHeader: string | null;
+    constructor(status: number, body: Partial<WixzelErrorBody>, headers?: {
+        retryAfter?: string | null;
+        balance?: string | null;
+    });
+}
+export interface WixzelClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Sent as `Wixzel-Version` to pin dated behaviour. */
+    apiVersion?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Injected in tests. */
+    fetch?: typeof fetch;
+}
+export declare class WixzelClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly apiVersion?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: WixzelClientOptions);
+    /** `wv_live_` or `wv_test_` — surfaced so an agent can tell which it is on. */
+    get keyMode(): 'live' | 'test' | 'unknown';
+    get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: Omit<RequestOptions, 'body'>): Promise<T>;
+    patch<T = unknown>(path: string, body: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    request<T = unknown>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,137 @@
+/**
+ * A small HTTP client for the Wixzel Voice API.
+ *
+ * Deliberately dependency-free: `fetch` is built into Node 20+, and the API's
+ * conventions (bearer key, JSON, structured errors with a request_id, cursor
+ * pagination, Idempotency-Key on money paths) are simple enough that a wrapper
+ * around fetch is the whole client.
+ */
+import { randomUUID } from 'node:crypto';
+import { VERSION } from './version.js';
+/**
+ * api.phone.wixzel.com, the default before 0.4.0, keeps serving the same API,
+ * so older releases of this package keep working.
+ */
+export const DEFAULT_BASE_URL = 'https://api.voice.wixzel.com';
+export const USER_AGENT = `wixzel-voice-mcp/${VERSION}`;
+/** Everything a caller needs to act on a failed request, in one object. */
+export class WixzelApiError extends Error {
+    status;
+    type;
+    code;
+    param;
+    requestId;
+    retryAfterSeconds;
+    balanceHeader;
+    constructor(status, body, headers = {}) {
+        super(body.message ?? `HTTP ${status}`);
+        this.name = 'WixzelApiError';
+        this.status = status;
+        this.type = body.type ?? (status >= 500 ? 'api_error' : 'invalid_request_error');
+        this.code = body.code ?? `http_${status}`;
+        this.param = body.param ?? null;
+        this.requestId = body.request_id ?? null;
+        this.retryAfterSeconds = headers.retryAfter ? Number(headers.retryAfter) || null : null;
+        this.balanceHeader = headers.balance ?? null;
+    }
+}
+export class WixzelClient {
+    baseUrl;
+    apiKey;
+    apiVersion;
+    timeoutMs;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new Error('WixzelClient needs an apiKey');
+        }
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.apiVersion = opts.apiVersion;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    }
+    /** `wv_live_` or `wv_test_` — surfaced so an agent can tell which it is on. */
+    get keyMode() {
+        if (this.apiKey.startsWith('wv_live_'))
+            return 'live';
+        if (this.apiKey.startsWith('wv_test_'))
+            return 'test';
+        return 'unknown';
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, opts = {}) {
+        return this.request('POST', path, { ...opts, body });
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, { body });
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(opts.query ?? {})) {
+            if (value === undefined || value === null || value === '')
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        if (this.apiVersion)
+            headers['Wixzel-Version'] = this.apiVersion;
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        const idempotencyKey = opts.idempotencyKey ?? (opts.idempotent ? randomUUID() : undefined);
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        // One retry budget for the whole call. 429s are never charged and carry
+        // Retry-After, so honouring it is the correct behaviour rather than
+        // surfacing a transient limit to the agent as a failure.
+        const maxAttempts = 3;
+        for (let attempt = 1;; attempt++) {
+            const response = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+            if (response.status === 429 && attempt < maxAttempts) {
+                const retryAfter = Number(response.headers.get('retry-after')) || 1;
+                await sleep(Math.min(retryAfter, 10) * 1000);
+                continue;
+            }
+            if (response.status === 204)
+                return null;
+            const text = await response.text();
+            let parsed = null;
+            if (text) {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = null;
+                }
+            }
+            if (!response.ok) {
+                const errorBody = parsed && typeof parsed === 'object' && 'error' in parsed
+                    ? (parsed.error ?? {})
+                    : { message: text || response.statusText };
+                throw new WixzelApiError(response.status, errorBody, {
+                    retryAfter: response.headers.get('retry-after'),
+                    balance: response.headers.get('x-wixzel-balance'),
+                });
+            }
+            return (parsed ?? text);
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/guide.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The operating guide an agent reads before it touches the account. Served
+ * as the server's `instructions`, as a resource, and reused by the prompts,
+ * so there is one place to keep it true.
+ *
+ * Built from the environment. A self-hosted install has no prepaid balance and
+ * no top-ups, and telling an agent to buy credit there would send it after a
+ * checkout that does not exist. The hosted text is unchanged.
+ */
+export declare function buildGuide(env?: NodeJS.ProcessEnv): string;
+export declare const GUIDE: string;

package/dist/guide.js

@@ -0,0 +1,86 @@
+/**
+ * The operating guide an agent reads before it touches the account. Served
+ * as the server's `instructions`, as a resource, and reused by the prompts,
+ * so there is one place to keep it true.
+ *
+ * Built from the environment. A self-hosted install has no prepaid balance and
+ * no top-ups, and telling an agent to buy credit there would send it after a
+ * checkout that does not exist. The hosted text is unchanged.
+ */
+import { consoleUrl, isSelfHosted } from './site.js';
+export function buildGuide(env = process.env) {
+    const selfHosted = isSelfHosted(env);
+    const site = consoleUrl(env);
+    const intro = selfHosted
+        ? `One API key, every voice engine, on your own server. ${site}`
+        : `One API key, one prepaid credit balance, every voice engine. ${site}`;
+    const money = selfHosted
+        ? `- COST accrues per second while a call is live and is itemised in usage events.
+  Nothing is charged on a self-hosted server; the figure estimates what the voice
+  providers bill. Amounts are micro-USD: 1,000,000 = $1.00.`
+        : `- CREDIT is a dollar balance. Cost accrues per second while a call is live and is
+  itemised in usage events. Amounts are micro-USD: 1,000,000 = $1.00.`;
+    const firstCall = selfHosted ? '5. place_call.' : '5. get_balance. Then place_call.';
+    const spending = selfHosted
+        ? `place_call and start_campaign make real phones ring, and the voice providers bill
+for every minute. Confirm with the user before calling them, say what it will do, and
+never retry one with a different idempotency_key: the same key returns the original
+result, a new key is a second call.`
+        : `place_call, start_campaign and create_topup spend money or make real phones ring.
+Confirm with the user before calling them, say what it will do, and never retry one
+with a different idempotency_key: the same key returns the original result, a new
+key is a second call. create_topup returns a checkout URL that a human must open;
+never try to pay.`;
+    return `# Wixzel Voice, for AI agents
+
+Wixzel Voice is the API and MCP server for building AI agents that place and answer
+real phone calls over your own SIP trunk, or talk to people in web and mobile apps.
+${intro}
+
+## The mental model
+
+- An AGENT is a prompt plus a voice engine (speech-to-text, LLM, text-to-speech,
+  or one realtime model that does all three).
+- A SIP TRUNK is the user's own carrier account (Twilio, Telnyx, Plivo, Vonage,
+  Bandwidth, Exotel, Vobiz, any SIP provider). Wixzel does not sell numbers or
+  minutes; the carrier's rates stay theirs.
+- A PHONE NUMBER is a number the user owns at that carrier, registered on the trunk.
+  Give it an inbound_agent_id and inbound calls are answered by that agent.
+- A CALL connects an agent to a real phone over the trunk. Outbound calls are placed
+  with place_call; campaigns place one call per lead.
+${money}
+
+## The order things go in
+
+1. list_engines: see which models are available right now and what they cost.
+   Never guess a model id.
+2. create_sip_trunk with the user's carrier credentials, then tell the user to
+   allowlist platform_ip with the carrier (outbound) and to point the carrier at
+   origination_uri (inbound). check_sip_trunk_status shows whether it is reachable.
+3. create_phone_number on that trunk.
+4. create_agent with a short spoken-style system_prompt, an opening_message, and a
+   voice from step 1. Set outbound_phone_number_id so calls have a caller id.
+${firstCall}
+6. get_call to watch status, read the transcript, and see cost_micros. If it did not
+   connect, failure_code and failure_reason say why and what to do.
+
+## Money and the real world
+
+${spending}
+
+Delete and revoke tools are permanent. revoke_api_key on the key this server is
+using will cut this server off.
+
+## Reading results
+
+- Errors carry a machine-readable code; act on the code and the Hint line.
+- Lists are cursor-paginated: pass next_cursor as starting_after until has_more is false.
+- 404 means "not on this account", including records owned by someone else.
+- The key's scopes decide what works. A permission error names the missing scope;
+  the fix is a new key from Dashboard -> API keys, not a retry.
+
+Docs: https://docs.voice.wixzel.com
+`;
+}
+export const GUIDE = buildGuide();
+//# sourceMappingURL=guide.js.map

package/dist/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../src/guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC3D,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAU;QACpB,CAAC,CAAC,wDAAwD,IAAI,EAAE;QAChE,CAAC,CAAC,gEAAgE,IAAI,EAAE,CAAC;IAC7E,MAAM,KAAK,GAAG,UAAU;QACpB,CAAC,CAAC;;4DAEkD;QACpD,CAAC,CAAC;sEAC4D,CAAC;IACnE,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,kCAAkC,CAAC;IACrF,MAAM,QAAQ,GAAG,UAAU;QACvB,CAAC,CAAC;;;oCAG0B;QAC5B,CAAC,CAAC;;;;kBAIQ,CAAC;IAEf,OAAO;;;;EAIT,KAAK;;;;;;;;;;;;;EAaL,KAAK;;;;;;;;;;;;EAYL,SAAS;;;;;;EAMT,QAAQ;;;;;;;;;;;;;;CAcT,CAAC;AACF,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Streamable HTTP mode: the hosted server at mcp.voice.wixzel.com, and the
+ * same thing on a laptop with `--http`.
+ *
+ * Stateless by design. Every request carries its own `Authorization: Bearer`,
+ * which is a Wixzel Voice API key — either pasted by a developer into
+ * `claude mcp add --header`, or issued by the API's OAuth server after the
+ * user consented in the console. Either way this process builds a fresh MCP
+ * server bound to that key, answers the request, and forgets it. Nothing here
+ * can mix two users up, because nothing here remembers anyone.
+ *
+ * The OAuth half lives in the API (api/oauth/index.ts there). This side only
+ * has to say where it is: RFC 9728 protected-resource metadata, and a 401 that
+ * points at it, are what make claude.ai's "add custom connector" flow work.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+export interface HttpOptions {
+    /** TCP port. 0 picks a free one (tests). */
+    port: number;
+    /** Interface to bind. Loopback by default: nginx terminates TLS in front. */
+    bind: string;
+    /** The resource identifier tokens are issued for, e.g. https://mcp.voice.wixzel.com/mcp */
+    publicUrl: string;
+    /**
+     * Other hostnames this same server answers on. A request that arrives on
+     * one is told the resource is publicUrl with that host. Defaults to
+     * hostAliases(publicUrl).
+     */
+    hostAliases?: readonly string[] | undefined;
+    /** The Wixzel Voice API, which is also the OAuth authorization server. */
+    apiBaseUrl: string;
+    /** The console the landing page links to. Defaults to voice.wixzel.com. */
+    consoleUrl?: string | undefined;
+    apiVersion?: string | undefined;
+    /** Used when a request carries no bearer. Refused on a public host; see resolveHttpOptions. */
+    fallbackKey?: string | undefined;
+    fetch?: typeof fetch | undefined;
+    log?: ((line: string) => void) | undefined;
+}
+/** The other names of the host in publicUrl, if it is the hosted server; none otherwise. */
+export declare function hostAliases(publicUrl: string): string[];
+/**
+ * The resource a request addressed: publicUrl, or the same URL on the alias
+ * host it arrived on (nginx passes the client's Host through). Any other Host
+ * gets publicUrl, so a forged header can only pick between our own names.
+ */
+export declare function resourceFor(publicUrl: string, aliases: readonly string[], hostHeader: string | undefined): string;
+/**
+ * Environment → options, with the one guard that matters: a fallback key on a
+ * host anyone can reach would hand that key's account to every anonymous
+ * caller. Refuse to start rather than trust the operator noticed.
+ */
+export declare function resolveHttpOptions(env: NodeJS.ProcessEnv, cliPort?: number): HttpOptions;
+type Verdict = 'ok' | 'rejected' | 'unknown';
+export declare class TokenProbe {
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private readonly cache;
+    constructor(apiBaseUrl: string, fetchImpl: typeof fetch);
+    check(apiKey: string): Promise<Verdict>;
+}
+export declare function protectedResourceMetadata(opts: HttpOptions, resource?: string): {
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+    scopes_supported: ("agents:read" | "agents:write" | "calls:read" | "calls:write" | "leads:read" | "leads:write" | "campaigns:read" | "campaigns:write" | "knowledge_bases:read" | "knowledge_bases:write" | "phone_numbers:read" | "phone_numbers:write" | "sip_trunks:read" | "sip_trunks:write" | "appointments:read" | "appointments:write" | "webhooks:read" | "webhooks:write" | "api_keys:read" | "api_keys:write" | "usage:read" | "billing:read" | "billing:write")[];
+    resource_name: string;
+    resource_documentation: string;
+};
+/** RFC 9728 §3: the well-known path carries the resource's own path as a suffix. */
+export declare function resourceMetadataUrl(publicUrl: string): string;
+export declare function createHttpHandler(opts: HttpOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningHttpServer {
+    server: Server;
+    /** The bound address, useful when port 0 was requested. */
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startHttp(opts: HttpOptions): Promise<RunningHttpServer>;
+export {};