> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# MCP server

The MCP server lets an AI assistant **read** the calls, usage, campaigns and Knowledge base of your Organization and carry out **three actions**. It uses the MCP protocol, supported by many assistants and development tools.

## Requirements

* A plan that includes both the public API and the AI assistants feature. Without them, requests get `403 feature_not_available`.
* An API key, or an OAuth connection approved by an Owner or an Admin in the app.

## Address and transport

* Address: `POST https://api.getvoxai.com/mcp` (the same host as the API, path `/mcp`).
* Transport: HTTP with a JSON response, without a session. Each HTTP request is one JSON-RPC message.
* `GET` and `DELETE` answer `405` with `Allow: POST`. JSON-RPC batches (arrays) are refused with `400`.
* Maximum body: 64 KB.
* A request carrying the `Origin` header (that is, coming from a browser) is refused with `403 origin_not_allowed`. MCP clients do not send it.

## Authentication

The server picks the method from the form of the `Authorization: Bearer …` header.

| Credential  | Form                     | Where it is valid                                                                |
| ----------- | ------------------------ | -------------------------------------------------------------------------------- |
| API key     | `vx_live_…`, `vx_test_…` | On v1 and on `/mcp`, with the same rules: allowed addresses, expiry, revocation. |
| OAuth token | `vxo_at_…`               | **Only on `/mcp`.** On `/v1` an OAuth token gets `401 invalid_api_key`.          |

Every `401` response of `/mcp` carries the `WWW-Authenticate` header with the address of the protected resource metadata (`resource_metadata`), so a compatible client starts the connection by itself.

### With an API key

Create the key in the app (Sviluppatori, then Accesso). For a read-only assistant these scopes are enough: `calls:read`, `usage:read`, `agents:read`, `campaigns:read`. Add `calls:start` and `campaigns:write` only if the assistant must be able to call and manage campaigns.

### With OAuth 2.1

OAuth is the method to use with assistants that do not accept a key pasted by hand. The flow is standard (authorization code with PKCE `S256`, mandatory) and the client runs it by itself:

1. The client calls `/mcp` without credentials and gets `401` with `resource_metadata`.
2. It reads the metadata of the resource (`/.well-known/oauth-protected-resource`) and of the authorization server (`/.well-known/oauth-authorization-server`).
3. It registers anonymously (`POST /oauth/register`) and gets a `client_id`.
4. It opens `/oauth/authorize`. The user's browser reaches the **consent page of the app**.
5. An **Owner or an Admin** of the Organization chooses the scopes and approves. A Member cannot approve. The page shows the name of the assistant (marked as not verified), the host of the redirect and the requested scopes. Action scopes are not preselected.
6. The client exchanges the code for the tokens (`POST /oauth/token`).

Durations:

| Item               | Duration                                     |
| ------------------ | -------------------------------------------- |
| Authorization code | 60 seconds, single use                       |
| Access token       | 1 hour                                       |
| Refresh token      | 30 days from issue, rotated at every use     |
| Connection         | at most 365 days, then it must be made again |

A refresh token can be used only once. If a refresh token that was already rotated is presented again after more than 30 seconds, the connection is revoked for safety.

### The connection key

When you approve a connection, VoxAI creates a **connection key**: an internal credential tied to the connection, which is not an API key. It does not appear among your keys, does not count towards their limit and is not rotated, but request limits, idempotency, traffic and the audit log rest on it, exactly as for a key. In the traffic page of the app the connection appears as «Connessione MCP» followed by the name of the assistant.

A connection:

* is always for the live environment and has no list of allowed addresses;
* has the powers of the approved scopes over the whole Organization;
* can be revoked in the app (Owners and Admins) at any time. It also stops working if whoever approved it is suspended, demoted to Member or deleted, or if the Organization is suspended;
* is at most 20 per Organization. A new consent by the same user to the same assistant replaces the previous one.

## Configuring an MCP client

Field names change from client to client: check your client's documentation.

**Desktop or web MCP client with an OAuth connection.** Add a custom connector (or a remote server) with the address `https://api.getvoxai.com/mcp`. The client registers by itself and opens the consent page of the app. Sign in as an Owner or an Admin, choose the scopes and approve.

**Command-line client or code editor with a key.** Declare a remote HTTP server with the address and the authentication header. The most common form is:

```json
{
  "mcpServers": {
    "voxai": {
      "url": "https://api.getvoxai.com/mcp",
      "headers": {
        "Authorization": "Bearer vx_live_…"
      }
    }
  }
}
```

Some clients use another root key instead of `mcpServers`, or a dedicated command to add the server. If yours accepts only local servers, use a local-to-remote bridge that forwards the `Authorization` header.

To try it without risk use a `vx_test_` key: `initialize`, `tools/list`, then `search_calls`. Note: a test key reads the Organization's real data, so the assistant sees the real calls. Only writes are simulated.

## Tools

The tools have no logic of their own: each call becomes a request to the matching v1 route, with the same scopes, limits, validation and idempotency. `tools/list` shows only the tools allowed by the scopes of the credential.

| Tool                    | v1 route                                    | Scope              |
| ----------------------- | ------------------------------------------- | ------------------ |
| `search_calls`          | `GET /v1/calls`                             | `calls:read`       |
| `missed_calls`          | `GET /v1/calls` with `missed=true`          | `calls:read`       |
| `get_call`              | `GET /v1/calls/{call_id}`                   | `calls:read`       |
| `get_call_transcript`   | `GET /v1/calls/{call_id}/transcript`        | `calls:read`       |
| `get_outbound_call`     | `GET /v1/outbound-calls/{outbound_call_id}` | `calls:read`       |
| `period_summary`        | `GET /v1/calls/summary`                     | `calls:read`       |
| `list_agents`           | `GET /v1/agents`                            | `agents:read`      |
| `usage`                 | `GET /v1/usage`                             | `usage:read`       |
| `concurrent_calls`      | `GET /v1/usage/concurrency`                 | `usage:read`       |
| `ask_knowledge`         | `POST /v1/knowledge/search`                 | `knowledge:search` |
| `list_campaigns`        | `GET /v1/campaigns`                         | `campaigns:read`   |
| `campaign_status`       | `GET /v1/campaigns/{campaign_id}`           | `campaigns:read`   |
| `campaign_results`      | `GET /v1/campaigns/{campaign_id}/contacts`  | `campaigns:read`   |
| `start_outbound_call`   | `POST /v1/calls`                            | `calls:start`      |
| `add_campaign_contacts` | `POST /v1/campaigns/{campaign_id}/contacts` | `campaigns:write`  |
| `pause_campaign`        | `POST /v1/campaigns/{campaign_id}/pause`    | `campaigns:write`  |

The three actions are `start_outbound_call`, `add_campaign_contacts` and `pause_campaign`. `start_outbound_call` starts a real call, which costs and cannot be undone. No tool deletes or exports data, and webhooks, Knowledge base writes, Caller requests and Agent configuration are not available.

Two ready prompts: `weekly_review` (the last 7 days) and `calls_to_return` (missed calls or calls to review). They are visible only if the credential has the scopes of the tools they name.

## Idempotency of the actions

Actions accept an optional `idempotency_key` argument (16 to 64 characters: letters, digits, `-`, `_`). If it is missing, the server derives one from the tool, the credential and the arguments: the same action with the same arguments within 24 hours is a replay and is not run again. To repeat an action on purpose, for example calling the same person again, pass a new `idempotency_key`. See [Idempotency](/concepts/idempotency).

## Errors and limits

* HTTP-level errors are JSON-RPC messages with `data.code`, which carries the v1 code (see [Errors](/concepts/errors)) plus two codes of `/mcp` only: `origin_not_allowed` (403) and `method_not_allowed` (405).
* When the internal request of a tool fails, the result has `isError: true` and its text is the v1 error body. A `429` also carries `retry_after` in seconds.
* If an internal request does not answer within 30 seconds, the result is an `upstream_timeout` error. If it was an action, it may have completed anyway: read the state again before repeating it.
* Request limits are those of v1, per key and per Organization. Every message counts: `initialize`, `tools/list`, `ping` and every tool call.

## Security: third-party text is data

Transcripts, summaries, collected data, names of campaigns and Agents and passages of Knowledge base documents are written or spoken by third parties and can contain instructions aimed at the assistant. The server says so in its instructions and in the results of the tools that return them. For an assistant that reads third-party text, give only read scopes: it is the prudent choice.