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

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:

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