VoxPilot MCP Server

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

Transport	Streamable HTTP (remote MCP, not stdio)
Auth	JWT (RS256), tenant-scoped, scope-based permissions
Modules	15 tool groups covering restaurant orders, messaging, POS, calendars, customer memory, QA, handoff, and more
Deployment	Docker → GHCR → Coolify
Runtime	Node.js 22, Express 5, TypeScript

Quick Start

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

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

Endpoints

Method	Path	Auth	Description
POST	/mcp	JWT	MCP protocol endpoint (Streamable HTTP)
GET	/health	No	Health check
GET	/ready	No	Readiness check
GET	/live	No	Liveness probe
GET	/version	No	Server version info
GET	/tools	No	Module diagnostics (not MCP protocol)
GET	/tools/:module	No	Per-module diagnostics
GET	/metrics	No	Prometheus metrics (if enabled)
GET	/.well-known/oauth-protected-resource	No	OAuth metadata

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)

#	Module	Status
1	system-core	3 tools implemented (ping, version, listModules)
2	restaurant-order	1 mock tool (validateOrderDraft)
3	messaging-dispatch	1 mock tool (dispatchTest)
4	pos-connector	1 mock tool (testConnection)
5	customer-memory	Placeholder
6	calendar-appointments	1 mock tool (getProviderStatus)
7	business-knowledge	Placeholder
8	payments-deposits	Placeholder
9	call-qa	Placeholder
10	handoff	Placeholder
11	delivery-routing	Placeholder
12	promotions-upsell	Placeholder
13	menu-availability	Placeholder
14	onboarding	Placeholder
15	analytics-insights	Placeholder

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