Content
# voxplo-mcp
Give your AI agent a phone. This MCP server lets any MCP client (Claude, Cursor, ChatGPT developer mode, and others) place real outbound AI phone calls through [Voxplo](https://voxplo.ai): the AI calls a person, conducts the conversation toward an objective, and returns a summary, transcript, and structured extracted fields.
- **Hosted (remote) server:** `https://mcp.voxplo.ai/mcp` (Streamable HTTP + OAuth, no install)
- **Local (stdio) server:** `npx voxplo-mcp` (this package)
- **Docs:** https://voxplo.ai/docs/agent-api/mcp
- **Tools:** `place_call`, `set_appointment`, `get_call`, `list_calls`
## Option A: hosted server (recommended)
No install. Add `https://mcp.voxplo.ai/mcp` as a remote MCP server in your client:
```json
{
"mcpServers": {
"voxplo": { "type": "streamable-http", "url": "https://mcp.voxplo.ai/mcp" }
}
}
```
In Claude: Settings, then Connectors, then "Add custom connector", paste `https://mcp.voxplo.ai/mcp`. Your browser opens Voxplo's consent screen; approve by pasting an Agent API key from your [Developers page](https://voxplo.ai/account/developers). The client never sees the key itself, only an OAuth token.
## Option B: local server (this package)
Prerequisites: Node 18+, a Voxplo Agent API key (starts with `bys_ak_`, from your [Developers page](https://voxplo.ai/account/developers)).
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:
```json
{
"mcpServers": {
"voxplo": {
"command": "npx",
"args": ["-y", "voxplo-mcp"],
"env": { "VOXPLO_API_KEY": "bys_ak_your_key_here" }
}
}
}
```
### Cursor
Add the same block to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`).
To point at a staging or self-hosted instance, add `"VOXPLO_API_BASE": "https://staging.example.com"` to the `env` block.
## Tools
### `place_call`
Places an outbound AI phone call toward an objective. Returns a `callId` immediately; the call runs asynchronously. Poll `get_call` with that `callId` until status is terminal.
**Inputs:**
| Field | Type | Required | Description |
|---|---|---|---|
| `to` | string | yes | Destination number in E.164 (e.g. `+14155550123`) |
| `objective` | string | yes | What the call should accomplish |
| `context` | string | no | Background context for the assistant |
| `fields` | array | no | Structured fields to extract (up to 20 items: `{ name, type?, description? }`) |
| `webhookUrl` | string | no | HTTPS URL to receive the signed result when the call ends |
| `callerId` | string | no | Caller ID override; must be a number on your account |
**Returns:** `{ callId, status }` where `status` is `queued` on success.
### `set_appointment`
Places an outbound AI phone call to set up a meeting. The assistant calls the person, agrees a time, and the result (poll `get_call`) carries an `outcome` (`appointment_set | callback_requested | declined | no_answer | failed`) and, when set, the appointment details (`startISO`, `timezone`, `durationMinutes`, `attendee`, `subject`). Returns a `callId` immediately.
**Inputs:**
| Field | Type | Required | Description |
|---|---|---|---|
| `to` | string | yes | Who to call, in E.164 |
| `subject` | string | yes | What the meeting is about |
| `durationMinutes` | number | no | Meeting length in minutes (default 30) |
| `timePreference` | string | no | Natural-language window, e.g. "weekday mornings next week" |
| `slots` | array | no | Specific start times to offer: `[{ startISO }]`, ISO-8601 with offset |
| `timezone` | string | no | IANA timezone for the appointment, e.g. `Asia/Jerusalem` |
| `autoBook` | boolean | no | Also book the agreed time on your connected calendar |
| `webhookUrl` | string | no | HTTPS URL to receive the signed result |
| `callerId` | string | no | Caller ID override; must be a number on your account |
### `get_call`
Fetches the current status and result of a call.
**Inputs:**
| Field | Type | Required | Description |
|---|---|---|---|
| `callId` | string | yes | The `callId` from `place_call` or `set_appointment` |
**Returns:** `{ id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }`
### `list_calls`
Lists recent calls placed by your account (most recent first).
**Inputs:**
| Field | Type | Required | Description |
|---|---|---|---|
| `limit` | number | no | Max calls to return (default 20, max 100) |
**Returns:** `{ calls: [ { id, to, objective, status, summary, createdAt, startedAt, endedAt, durationSec, error? } ] }`
## Call statuses
| Status | Terminal? | Meaning |
|---|---|---|
| `queued` | no | Call accepted, not yet dialing |
| `ringing` | no | Dialing the destination |
| `in_progress` | no | Call is live |
| `completed` | yes | Call finished normally |
| `no_answer` | yes | Destination did not pick up |
| `voicemail` | yes | Reached voicemail |
| `declined` | yes | Call was rejected |
| `failed` | yes | Technical failure |
## Place your first call
1. Configure your MCP client as above.
2. Ask your assistant: "Place a call to +14155550123 with the objective: confirm the meeting time for tomorrow at 2pm."
3. The assistant calls `place_call` and gets back a `callId`.
4. Ask: "Check on call `<callId>` -- did it complete?"
5. The assistant calls `get_call` and returns the status, summary, and any extracted fields.
## Safety
Outbound destinations are screened server-side (premium-rate, satellite, and other high-risk routes are blocked), calls carry an AI disclosure when asked, and the call-placing tools are annotated `openWorldHint: true` so clients ask for confirmation before dialing. Details: https://voxplo.ai/security
## Development
Run tests:
```bash
node --test
```
Smoke test (with dummy key, should print "ready on stdio" to stderr):
```bash
VOXPLO_API_KEY=bys_ak_test node src/server.js
```
## Links
- Voxplo: https://voxplo.ai
- Agent API reference: https://voxplo.ai/docs/agent-api
- OpenAPI spec: https://www.voxplo.ai/openapi.json
- Hosted MCP server card: https://mcp.voxplo.ai/.well-known/mcp/server-card.json
- License: MIT
