Skip to navigation

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.

CredentialFormWhere it is valid
API keyvx_live_…, vx_test_…On v1 and on /mcp, with the same rules: allowed addresses, expiry, revocation.
OAuth tokenvxo_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:

ItemDuration
Authorization code60 seconds, single use
Access token1 hour
Refresh token30 days from issue, rotated at every use
Connectionat 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:

{
"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.

Toolv1 routeScope
search_callsGET /v1/callscalls:read
missed_callsGET /v1/calls with missed=truecalls:read
get_callGET /v1/calls/{call_id}calls:read
get_call_transcriptGET /v1/calls/{call_id}/transcriptcalls:read
get_outbound_callGET /v1/outbound-calls/{outbound_call_id}calls:read
period_summaryGET /v1/calls/summarycalls:read
list_agentsGET /v1/agentsagents:read
usageGET /v1/usageusage:read
concurrent_callsGET /v1/usage/concurrencyusage:read
ask_knowledgePOST /v1/knowledge/searchknowledge:search
list_campaignsGET /v1/campaignscampaigns:read
campaign_statusGET /v1/campaigns/{campaign_id}campaigns:read
campaign_resultsGET /v1/campaigns/{campaign_id}/contactscampaigns:read
start_outbound_callPOST /v1/callscalls:start
add_campaign_contactsPOST /v1/campaigns/{campaign_id}/contactscampaigns:write
pause_campaignPOST /v1/campaigns/{campaign_id}/pausecampaigns: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.

Errors and limits

  • HTTP-level errors are JSON-RPC messages with data.code, which carries the v1 code (see 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.