voxplo-mcp

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. [phone])
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 [phone] with the objective: confirm the meeting time for tomorrow at 2pm."
• The assistant calls place_call and gets back a callId.
• Ask: "Check on call <callId> -- did it complete?"
• 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