voxaphone-mcp

The official Model Context Protocol (MCP) server for Voxana AI — a sub-800ms, zero-data-at-rest voice execution substrate. It bridges LLM reasoning agents (Claude, Vapi, Retell, OpenAI, etc.) to real-time telephony and business action workflows.

Design principles

• Zero data-at-rest. Call state, context, and action records live only in a process-local Map (src/store/volatile-state.ts). Nothing is ever written to disk or a database, and no raw transcript/audio content is logged.

• TTL-bounded memory. Every session carries an expiry derived from max_duration_seconds; a background sweeper evicts stale sessions so memory usage stays bounded for the life of the process.

• Strict validation. Every tool input is validated with Zod before any handler logic runs.

• Clean error contracts. All handlers are wrapped in safeExecute, so callers always get back structured { error, data } / { error, code, message } JSON — never an unhandled exception.

Related MCP server: Dial MCP Server

Tools

Tool annotations

Every tool declares all four MCP behavioral hints under annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), set to values reflecting actual runtime behavior rather than defaults:

These are advisory metadata consumed by MCP hosts and directory trust indexes — they do not themselves enforce safety. The actual guarantees (schema validation, session existence checks, structured error handling) live in the handler code in src/tools/index.ts.

Getting started

npm install
npm run build
npm start

For local development with live reload:

npm run dev

By default the server speaks MCP over stdio, which is how hosts like Claude Desktop or Claude Code launch it as a subprocess. Point your MCP host config at dist/server.js (or src/server.ts via tsx in dev mode).

Example MCP host config (stdio)

{
  "mcpServers": {
    "voxaphone": {
      "command": "node",
      "args": ["/absolute/path/to/voxaphone-mcp/dist/server.js"]
    }
  }
}

SSE / HTTP transport

Setting VOXA_TRANSPORT=sse signals intent to run over HTTP instead of stdio. Because that mode requires binding StreamableHTTPServerTransport to a listening HTTP server (e.g. via Express), which is deployment-specific, src/server.ts raises a clear error telling you to wire that host yourself rather than silently doing nothing.

Project layout

voxaphone-mcp/
├── package.json
├── tsconfig.json
└── src/
    ├── server.ts              # MCP Server wiring, transport, shutdown
    ├── store/
    │   └── volatile-state.ts  # In-memory, TTL-bounded session store
    └── tools/
        └── index.ts           # Zod schemas + handlers for all 4 tools

Compliance note

This server is built to avoid persisting call content, which is a necessary but not sufficient condition for HIPAA/GDPR alignment — full compliance also depends on your deployment environment (network transport encryption, upstream telephony provider agreements, access controls, etc.), which are outside the scope of this codebase.