Connect

MCP server

MCP (Model Context Protocol) lets an AI editor - Claude Code, Cursor, Windsurf, and others - pull in a tool from an outside service at runtime and actually use it, not just talk about it. Once volai is connected, just tell your editor what you want ("send an SMS", "create an agent"), and it picks the right tool and calls it - no code, no reading API docs.

Installation

The server runs at https://volai.cz/mcp. You authenticate with an API key from the portal - the first step of the Quickstart shows you how to get one. Pick your editor:

One command in the terminal and you're done:

bash

claude mcp add --transport http volai https://volai.cz/mcp \
  --header "Authorization: Bearer vk_YOUR_KEY"

Tools

All 31 tools go through the same service layer as the REST API and the portal - same rules, same prices, same limits (including the 60 requests per minute: MCP and REST share it, since they run on the same key). The editor picks the right tool based on its description - you just tell it what you want.

get_balance

Check the current credit balance - how much is left to spend.

list_numbers

List the account's phone numbers and their routing.

search_available_numbers

The user is looking for a number to buy - lists what is currently available.

buy_number

The user wants a new phone number for their app - Prague, Brno, or a 910 internet number that isn't tied to a region.

find_number_address

Look up a business address in the carrier's directory - the first step of ordering a number from another region. Send the whole address as query, or walk the cascade step by step.

order_number_from_region

The user wants a number from a region that isn't in the standard offer (Ostrava, Plzeň, Budějovice...). It's handled on the spot, usually within a minute.

list_number_orders

Status of numbers ordered from other regions - where processing got stuck or what's already done.

set_number_routing

Switch where a number routes calls - to an agent, forwarding, SIP, or nowhere.

get_sip_credentials

The user wants to connect a number to their own softphone or PBX.

create_relay_lease

Set up an outbound call from your own (BYO) voice agent through the relay - prepares a one-time connection between your number and the destination.

list_relay_leases

List active relay connections for your own agent.

cancel_relay_lease

Cancel an unused relay connection so it doesn't block a slot in the pool.

send_sms

Send a text message to a Czech or Slovak number.

list_messages

List the history of sent SMS.

make_call

Call a number (to) - pass exactly one parameter: agentId (the voice agent handles the call), from (a direct connection between two numbers, no agent), or systemPrompt (a trial call with no number of your own, right away with no agent to set up).

list_calls

List call history (inbound and outbound).

get_call

Detail of a specific call, including the transcript and summary - typically when the agent needs to comment on a call. waitSecs waits for the call to end instead of polling.

add_to_dnc

Add a number to the do-not-call list, so no agent (built-in or your own) calls it again.

list_dnc

List numbers on the do-not-call list.

remove_from_dnc

Remove a number from the do-not-call list once it's allowed to be called again.

list_voices

Check the valid values for voiceId on create_agent/update_agent - a voice catalog, currently a single entry.

create_agent

Create a new voice agent from a description of the task - including tools (toolIds), handoff to a human (transferTo), and data to capture from the call (dataFields) right away.

list_agents

List the account's existing agents.

update_agent

Edit an existing agent's prompt, voice, or number - also toggles tools, handoff, recording (recordCalls), and captured data.

delete_agent

Delete an agent that's no longer in use.

list_tools

List the account's webhook tools - typically before assigning one to an agent. Header values are returned masked.

create_tool

The user wants the agent to call their API during a call - verify an order, log a booking, check an open slot.

update_tool

Change the URL, description, headers, or parameters of an existing tool.

delete_tool

Delete a tool that's no longer in use - returns the agents it stops working for.

get_webhook

Check where events are currently being sent, and whether a webhook is set up at all.

set_webhook

Set the URL where volai should send events (call completed, SMS sent...). An empty url removes the webhook.

Agent tools are two steps, not one

create_tool only creates a tool - it doesn't assign it to any agent on its own. Only update_agent with toolIds assigns it, and the field is ALWAYS sent IN FULL: whatever you leave out won't be on the agent after the update. The same tool can be used by multiple agents - it belongs to the account.

Recording audio doesn't travel over MCP. get_call tells you via the hasRecording field whether a recording exists, and the MP3 itself is downloaded from GET /v1/calls/{id}/recording with the same API key - a binary body has no place in a tool's response.

What MCP deliberately can't do

The only ACTION from the REST API deliberately missing from the tool list is releasing a purchased number (DELETE /v1/numbers/{e164}). You can buy a number through MCP, but not release one - that's what the portal or REST API is for, so one misread sentence can't cost you the number printed on your flyer. The second endpoint without a tool is fetching a recording (see above) - it returns audio, not JSON.

A single agent's detail and a single SMS's detail don't get their own tool, because they wouldn't add anything - list_agents and list_messages return the same fields as the detail endpoints. The "have your own agent call you" trial call (REST POST /v1/agents/{id}/test-call) also doesn't get its own tool - make_call with an agentId parameter is the same call, just without its own daily cap of three attempts.

A trial call with no number of your own is a different thing, and has dedicated support in make_call: the systemPrompt parameter calls from volai's shared demo number, with no number to buy and no agent to set up.

Tax invoices and billing details stay outside both MCP and REST - they only live in the portal (/credit and /settings).

What the editor reads about a tool beforehand

Every tool reports how it behaves, so the editor knows when to ask first and when it can just act. It isn't a security boundary (that's credit, rate limits, and the do-not-call list, all enforced on our side) - it's why a good client asks before it deletes an agent:

Property	What it means
`readOnlyHint`	The tool only reads - it changes nothing and costs nothing. All `list_` and `get_` tools.
`destructiveHint`	A change you can't undo, or one that lifts protection that was in place - `delete_agent`, `delete_tool`, `cancel_relay_lease`, `remove_from_dnc`. The editor should ask before these.
`idempotentHint`	Repeating the call with the same values adds nothing. Paid actions (`send_sms`, `make_call`, `buy_number`, `order_number_from_region`) and creation actions (`create_agent`, `create_relay_lease`, `create_tool`) deliberately lack this hint: calling them again sends a second SMS, charges a second time, or creates a second record, so the editor must not retry them on its own after a timeout.
`openWorldHint`	The action reaches outside your account records, into the phone network or the carrier's directories.

Every tool's result also comes twice: as a readable sentence with a JSON block, and as machine-readable structuredContent - a client that supports it reads the data from there instead of parsing it out of the text.

Try it out

Once MCP is connected, try telling your editor one of these (your own words are fine - there's no exact wording to match):

Call me right now at +420777123456 and try the role of a cafe receptionist - I don't want to set up my own number or agent just for this.
Buy me a phone number and set up an agent on it that takes coffee orders.
Text +420777123456 that their order is ready for pickup.
List my last 10 calls and give me a short summary of each.
Check how much credit I have left, and warn me if it's running low.
Create an agent for a short satisfaction survey and call my own number with it right away so I can try it out.
Add a tool for my receptionist that checks order status on my API, and turn it on for her.
Have the agent capture the caller's name and whether it's urgent from every call.

Security

MCP uses the same API key as the REST API - anyone who has it can spend your credit on your behalf: buying numbers, making calls, sending SMS, creating agents.

Treat your key like a password

Never put it in frontend code, commit it to a GitHub repo, or send it to anyone in plain text. If someone else sees it, they can spend your credit until it runs out.

Suspect a leak, or just want to rotate the key? One button handles it: in the portal, under API and MCP, delete the key - it stops working immediately and can't be restored. Create a new one and update it in your editor's config.

REST API

Complete reference for every endpoint, incl. agent tools and recordings.

Voice agent

System prompt, tools, handoff to a human, recordings and structured call data.

Webhooks

Events, structured data in the body, signature verification, retries on failure.

Bring your own agent

Connect a third-party platform (ElevenLabs, Asterisk...) - no agent surcharge.