ZeroVoice MCP Bridge

The ZeroVoice MCP bridge exposes 25 telephony tools that any MCP-compatible AI agent (Claude Code, Cody, custom agents) can call to make phone calls, send SMS, manage contacts, and query analytics.

Setup

1. Add to .mcp.json

{
  "mcpServers": {
    "zerovoice": {
      "command": "python3",
      "args": ["path/to/ZeroVoice/scripts/mcp_server.py"],
      "env": {
        "ZEROVOICE_API_URL": "https://your-instance.up.railway.app",
        "ZEROVOICE_API_TOKEN": "eyJ..."
      }
    }
  }
}

2. Environment variables

Variable	Required	Description
ZEROVOICE_API_URL	No	API base URL (default: http://localhost:8000)
ZEROVOICE_API_TOKEN	Yes	Valid JWT bearer token for authentication

3. Generate a service token

curl -X POST https://your-instance/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@company.com", "password": "..."}'

The returned access_token goes into ZEROVOICE_API_TOKEN.

---

Available tools (25)

Calls (6 tools)

Tool	Description
make_call	Place an outbound phone call via Twilio
get_live_calls	Get currently active calls (ringing/active)
get_call_logs	Search call history with filters
get_call	Get details for a specific call by ID
transfer_call	Transfer an active call to another number
hangup_call	Hang up / end an active call

SMS (1 tool)

Tool	Description
send_sms	Send an SMS/MMS message via Twilio

Contacts (3 tools)

Tool	Description
create_contact	Create a new contact in the organization
list_contacts	List contacts with optional search and pagination
get_contact_call_history	Get call history for a specific contact

Phone Numbers (5 tools)

Tool	Description
list_numbers	List phone numbers owned by the organization
search_available_numbers	Search for numbers available for purchase
purchase_number	Purchase a phone number
configure_number	Update routing configuration for a number
release_number	Release (give up) a phone number

Transcripts & Recordings (4 tools)

Tool	Description
get_transcript	Get the transcript for a specific call
search_transcripts	Search call transcripts by keyword
list_transcripts	List transcripts, optionally by campaign
get_call_recordings	Get recordings for a specific call

Compliance (1 tool)

Tool	Description
check_dnc	Check if a phone number is on the Do-Not-Call list

Voicemails (2 tools)

Tool	Description
list_voicemails	List voicemails, optionally filtered by status
get_voicemail	Get a specific voicemail with transcription

Analytics (2 tools)

Tool	Description
get_call_volume	Get call volume analytics (by hour/day/week/month)
get_agent_performance	Get agent performance metrics

Health (1 tool)

Tool	Description
health_check	Check API health (DB, Twilio, Stripe, ZeroDB)

---

Example: Agent-driven outbound call

Agent: I need to call the prospect at +15551234567.

→ Tool call: check_dnc(phone_number="+15551234567")
← Result: {"items": [], "total": 0}  (not on DNC)

→ Tool call: make_call(from_number="+18317773598", to_number="+15551234567", record=true)
← Result: {"id": "abc-123", "status": "queued", ...}

→ Tool call: get_call(call_id="abc-123")
← Result: {"status": "active", "duration_seconds": 45, ...}

Example: SMS follow-up after a call

→ Tool call: send_sms(
    from_number="+18317773598",
    to_number="+15551234567",
    body="Thanks for speaking with us! Here's the link to schedule a demo: ..."
  )
← Result: {"id": "sms-456", "status": "sent"}

---

Architecture

The MCP bridge is a thin HTTP client layer built with FastMCP. Each tool maps to one ZeroVoice REST endpoint:

Claude Code / Agent
    │ MCP stdio protocol
    ▼
mcp_server.py (FastMCP, 25 tools)
    │ HTTP + JWT
    ▼
ZeroVoice API (FastAPI)
    │
    ▼
Twilio (calls, SMS, numbers)

The bridge runs as a local process (stdio transport), not a network server. It inherits the API's rate limits (200 req/min per tenant) and DNC/compliance enforcement.