{
  "markdown": "# voxplo-mcp\n\nGive 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.\n\n- **Hosted (remote) server:** `https://mcp.voxplo.ai/mcp` (Streamable HTTP + OAuth, no install)\n- **Local (stdio) server:** `npx voxplo-mcp` (this package)\n- **Docs:** https://voxplo.ai/docs/agent-api/mcp\n- **Tools:** `place_call`, `set_appointment`, `get_call`, `list_calls`\n\n## Option A: hosted server (recommended)\n\nNo install. Add `https://mcp.voxplo.ai/mcp` as a remote MCP server in your client:\n\n```json\n{\n  \"mcpServers\": {\n    \"voxplo\": { \"type\": \"streamable-http\", \"url\": \"https://mcp.voxplo.ai/mcp\" }\n  }\n}\n```\n\nIn 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.\n\n## Option B: local server (this package)\n\nPrerequisites: Node 18+, a Voxplo Agent API key (starts with `bys_ak_`, from your [Developers page](https://voxplo.ai/account/developers)).\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:\n\n```json\n{\n  \"mcpServers\": {\n    \"voxplo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"voxplo-mcp\"],\n      \"env\": { \"VOXPLO_API_KEY\": \"bys_ak_your_key_here\" }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd the same block to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`).\n\nTo point at a staging or self-hosted instance, add `\"VOXPLO_API_BASE\": \"https://staging.example.com\"` to the `env` block.\n\n## Tools\n\n### `place_call`\n\nPlaces 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.\n\n**Inputs:**\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `to` | string | yes | Destination number in E.164 (e.g. `+14155550123`) |\n| `objective` | string | yes | What the call should accomplish |\n| `context` | string | no | Background context for the assistant |\n| `fields` | array | no | Structured fields to extract (up to 20 items: `{ name, type?, description? }`) |\n| `webhookUrl` | string | no | HTTPS URL to receive the signed result when the call ends |\n| `callerId` | string | no | Caller ID override; must be a number on your account |\n\n**Returns:** `{ callId, status }` where `status` is `queued` on success.\n\n### `set_appointment`\n\nPlaces 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.\n\n**Inputs:**\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `to` | string | yes | Who to call, in E.164 |\n| `subject` | string | yes | What the meeting is about |\n| `durationMinutes` | number | no | Meeting length in minutes (default 30) |\n| `timePreference` | string | no | Natural-language window, e.g. \"weekday mornings next week\" |\n| `slots` | array | no | Specific start times to offer: `[{ startISO }]`, ISO-8601 with offset |\n| `timezone` | string | no | IANA timezone for the appointment, e.g. `Asia/Jerusalem` |\n| `autoBook` | boolean | no | Also book the agreed time on your connected calendar |\n| `webhookUrl` | string | no | HTTPS URL to receive the signed result |\n| `callerId` | string | no | Caller ID override; must be a number on your account |\n\n### `get_call`\n\nFetches the current status and result of a call.\n\n**Inputs:**\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `callId` | string | yes | The `callId` from `place_call` or `set_appointment` |\n\n**Returns:** `{ id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }`\n\n### `list_calls`\n\nLists recent calls placed by your account (most recent first).\n\n**Inputs:**\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `limit` | number | no | Max calls to return (default 20, max 100) |\n\n**Returns:** `{ calls: [ { id, to, objective, status, summary, createdAt, startedAt, endedAt, durationSec, error? } ] }`\n\n## Call statuses\n\n| Status | Terminal? | Meaning |\n|---|---|---|\n| `queued` | no | Call accepted, not yet dialing |\n| `ringing` | no | Dialing the destination |\n| `in_progress` | no | Call is live |\n| `completed` | yes | Call finished normally |\n| `no_answer` | yes | Destination did not pick up |\n| `voicemail` | yes | Reached voicemail |\n| `declined` | yes | Call was rejected |\n| `failed` | yes | Technical failure |\n\n## Place your first call\n\n1. Configure your MCP client as above.\n2. Ask your assistant: \"Place a call to +14155550123 with the objective: confirm the meeting time for tomorrow at 2pm.\"\n3. The assistant calls `place_call` and gets back a `callId`.\n4. Ask: \"Check on call `<callId>` -- did it complete?\"\n5. The assistant calls `get_call` and returns the status, summary, and any extracted fields.\n\n## Safety\n\nOutbound 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\n\n## Development\n\nRun tests:\n\n```bash\nnode --test\n```\n\nSmoke test (with dummy key, should print \"ready on stdio\" to stderr):\n\n```bash\nVOXPLO_API_KEY=bys_ak_test node src/server.js\n```\n\n## Links\n\n- Voxplo: https://voxplo.ai\n- Agent API reference: https://voxplo.ai/docs/agent-api\n- OpenAPI spec: https://www.voxplo.ai/openapi.json\n- Hosted MCP server card: https://mcp.voxplo.ai/.well-known/mcp/server-card.json\n- License: MIT",
  "bytes": 6168,
  "sha": "cbeacd662f471881fa9ab2862162c2c3cde9a2b78b024a793dc3278ecfc90225",
  "repo_slug": "allexp1/voxplo-mcp",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_voxplo_voxplo_c05f68fe/readme"
}