---
title: "MCP Bridge"
description: "ZeroVoice MCP Bridge — connect voice capabilities to AI agents via MCP protocol"
canonical: "https://docs.ainative.studio/docs/zerovoice/mcp-bridge"
last-updated: "2026-11-02T18:12:43.468Z"
---

# MCP Bridge

Source: https://docs.ainative.studio/docs/zerovoice/mcp-bridge

> ZeroVoice MCP Bridge — connect voice capabilities to AI agents via MCP protocol

# 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`

```json
{
  "mcpServers": {
    "zerovoice": {
      "command": "python3",
      "args": ["path/to/ZeroVoice/scripts/mcp_server.py"],
      "env": {
        "ZEROVOICE_API_URL": "https://your-zerovoice-instance.example.com",
        "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

```bash
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](https://gofastmcp.com). 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.