Voxplo
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: 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:
{
"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. 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).
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:
{
"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
- Configure your MCP client as above.
- Ask your assistant: "Place a call to +14155550123 with the objective: confirm the meeting time for tomorrow at 2pm."
- The assistant calls
place_calland gets back acallId. - Ask: "Check on call
<callId>-- did it complete?" - The assistant calls
get_calland 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:
node --test
Smoke test (with dummy key, should print "ready on stdio" to stderr):
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
Server Config
{
"mcpServers": {
"voxplo": {
"type": "streamable-http",
"url": "https://mcp.voxplo.ai/mcp"
}
}
}