VoxPilot MCP Server

Production-ready remote Model Context Protocol (MCP) server for the VoxPilot AI SaaS platform.

Quick Start

# Local dev
npm install
cp .env.local.example .env
npm run dev

# Docker
npm run docker:build
npm run docker:run

Related MCP server: Metrx MCP Server

Endpoints

MCP Endpoint

The real MCP protocol happens at /mcp. The /tools/:module URLs are module aliases for diagnostics, documentation, and backend configuration clarity — they do not replace /mcp.

Local Caddy

mcp.voxpilot.test {
  tls internal
  reverse_proxy mcp-server:8080
}

Add to /etc/hosts:

127.0.0.1 mcp.voxpilot.test

Auth Model

JWT tokens issued by VoxPilot NestJS backend with these claims:

{
  "iss": "voxpilot-api",
  "aud": "voxpilot-mcp",
  "sub": "user_or_service_id",
  "tenantId": "tenant_uuid",
  "role": "owner | admin | agent | system",
  "scopes": ["mcp:tools:read", "orders:read", "..."],
  "callId": "optional",
  "sessionId": "optional"
}

Dev Bypass

Set DEV_BYPASS_AUTH=true in .env for local development (blocked in production).

DEV_BYPASS_AUTH=true
DEV_TENANT_ID=dev-tenant
DEV_SUBJECT=dev-user
DEV_ROLE=system
DEV_SCOPES=mcp:tools:read,orders:read,orders:write,messages:send,pos:read,pos:write,customers:read,customers:write,calendar:read,calendar:write,business:read,payments:write,qa:write,handoff:write,analytics:read

Tool Modules (15)

Integration

VoxPilot NestJS backend calls the MCP server via POST to /mcp with:

Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json, text/event-stream

Example JSON-RPC tool call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "systemCore.ping",
    "arguments": { "message": "hello" }
  }
}

Spec-Driven Development

Each module is implemented spec-by-spec. See specs/ for the 16 spec files (000–015).
No module is implemented without a spec.

What is intentionally not yet implemented

• Real WhatsApp, Telegram, Slack, SMS, email dispatch

• Real POS connections (TastyIgniter, Odoo)

• Real Google Calendar / Outlook integration

• Real payment processing (Stripe)

• Real call QA analysis

• Real customer memory persistence

• Real analytics queries

• Redis-backed queues or caching

• PostgreSQL audit persistence

• OpenTelemetry export

Production Deployment

# docker-compose.yml (VoxPilot root stack)
mcp-server:
  build:
    context: ./voxpilot-mcp-server
    dockerfile: docker/Dockerfile
  ports:
    - "8080:8080"
  env_file:
    - .env
  networks:
    - voxpilot

Image published to ghcr.io/nehilor/voxpilot-mcp-server with tags latest, develop, sha-<shortsha>.