# Voxplo Mcp

> Give AI agents a phone: MCP server for Voxplo outbound AI phone calls. Hosted at mcp.voxplo.ai/mcp or run locally via npx voxplo-mcp.

- **Type:** MCP server
- **Install:** `agentstack add mcp-allexp1-voxplo-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [allexp1](https://agentstack.voostack.com/s/allexp1)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [allexp1](https://github.com/allexp1)
- **Source:** https://github.com/allexp1/voxplo-mcp
- **Website:** https://voxplo.ai

## Install

```sh
agentstack add mcp-allexp1-voxplo-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `` -- 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [allexp1](https://github.com/allexp1)
- **Source:** [allexp1/voxplo-mcp](https://github.com/allexp1/voxplo-mcp)
- **License:** MIT
- **Homepage:** https://voxplo.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-allexp1-voxplo-mcp
- Seller: https://agentstack.voostack.com/s/allexp1
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.