Napojení
MCP server
MCP (Model Context Protocol) umožní AI editoru - Claude Code, Codex CLI, Codex desktop, Cursor, Windsurfu a dalším - načíst nástroj z cizí služby a použít ho podle zadání. Po připojení začni read-only ověřením; další práce, například SMS, úkoly nebo hlasový agent, je volitelná.
Přihlášení přes účet volai
V Codex CLI, Codex desktop, Claude Code nebo jiném klientovi s OAuth přidej vzdálený MCP server https://volai.cz/mcp. Otevři přihlášení, přihlas se k volai a zkontroluj aplikaci i rozsah přístupu. Souhlas zahrnuje práci s daty účtu, hlasové agenty a placené hovory, SMS a objednávky čísel.
OAuth připojení je první volba: příklady pro Claude Code, Codex CLI a Codex desktop najdeš v záložkách níže. Připojení je hotové až po read-only načtení, ne po pouhém uložení konfigurace.
claude mcp add --transport http --scope user volai 'https://volai.cz/mcp'
claude mcp login volaiPřipojené aplikace najdeš v portálu v části API a MCP. Přístup můžeš okamžitě odvolat; změna hesla jej také zneplatní. OAuth token platí pro MCP, REST dál používá API klíč.
OAuth připojení je dostupné přímo přes adresu serveru. Zařazení volai do oficiálního katalogu OpenAI nebo Anthropic podléhá jejich schválení; vlastní plugin marketplace takové schválení neznamená.
Fallback: ruční připojení přes API klíč
Server běží na https://volai.cz/mcp. Když klient OAuth neumí, použij existující API klíč z portálu; návod je v Quickstartu. Vyber si editor. Nový klíč není součástí povinného připojení:
Jeden příkaz v terminálu a je hotovo:
claude mcp add --header 'Authorization: Bearer vk_TVUJ_KLIC' --transport http --scope user volai 'https://volai.cz/mcp'Rovnou přidat do editoru
Claude Code
claude mcp add --header 'Authorization: Bearer vk_TVUJ_KLIC' --transport http --scope user volai 'https://volai.cz/mcp'Po instalaci nahraď vk_TVUJ_KLIC svým klíčem z průvodce AI asistent v portálu.
Ověř připojení bez utrácení kreditu
Po přidání serveru nech editor nejdřív zavolat get_balance. Nástroj jen čte, nic nestojí a zaznamená, že toto MCP připojení funguje. Další bezpečná kontrola je list_agents. Nevolej, neposílej SMS ani nekupuj číslo jen kvůli ověření spojení.
Kalendář
Účet nejdřív připoj v Připojení. Pak použij list_integrations -> list_calendars -> list_calendar_events -> get_calendar_event. Změnu připrav přes propose_calendar_update, ukaž původní událost a návrh a až po potvrzení volej confirm_calendar_update s confirm: true. Při calendar_stale_revision načti událost znovu a nech schválit nový návrh. U Apple použij jako eventId přesnou hodnotu externalId z výpisu událostí. Jde o neprůhledný identifikátor záznamu CalDAV, ne o iCalendar UID; nesestavuj ho ani nedekóduj.
Časové údaje posílej s pásmem, například 2026-10-05T10:00:00+02:00. Celodenní události používají YYYY-MM-DD a konec je výlučný. Seznam vrací nejvýš 50 událostí; pro další stránku pošli nextPageToken jako pageToken se stejnými filtry. Toto rozhraní upravuje existující události. Apple recurring:true představuje celou sérii: změna upraví její základ a zachová jednotlivé výjimky. Apple události bez pásma zachovávají místní čas bez posunu.
Kromě Google Kalendáře funguje i Apple Calendar (připojuje se heslem pro konkrétní aplikaci). Nástroje list_calendar_events i get_calendar_event umí obojí; calendarId musí být jedna z hodnot z list_calendars, jinak přijde 400 calendar_invalid_calendar.
Podrobný postup (připojení účtu, co rozhraní umí a neumí) je v průvodci Připojení.
Fakturoid & ABRA Flexi
Fakturoid nebo ABRA Flexi nejdřív připoj v Připojení. Pak použij list_integrations -> list_invoices (volitelný search) -> get_invoice pro čerstvý důkaz. Seznam vrací prvních 40 výsledků Fakturoidu nebo 50 ABRA; podle potřeby zpřesni hledání. amountDueMinor používá nejmenší jednotky měny. null a status: unknown nejsou důkazem úhrady. Tyto nástroje faktury pouze čtou.
Nástroje
Všech 92 nástrojů volá stejnou servisní vrstvu jako REST API a portál - stejná pravidla, stejné ceny, stejné limity (i těch 60 požadavků za minutu: MCP a REST je sdílejí, protože jedou na tomtéž klíči). Editor si podle popisu každého nástroje sám vybere ten správný, tobě stačí napsat, co chceš.
Účet
get_accountGET /v1/accountupdate_accountPATCH /v1/accountupdate_billing_detailsPUT /v1/account/billinglist_api_keysGET /v1/api-keysPřipojení
list_integrationsGET /v1/integrationsFaktury
list_invoicesGET /v1/integrations/{id}/invoicesget_invoiceGET /v1/integrations/{id}/invoices/{invoiceId}Kalendáře
list_calendarsGET /v1/integrations/{id}/calendarslist_calendar_eventsGET /v1/integrations/{id}/eventsget_calendar_eventGET /v1/integrations/{id}/events/{eventId}propose_calendar_updatePOST /v1/integrations/{id}/events/{eventId}/proposeconfirm_calendar_updatePATCH /v1/integrations/{id}/events/{eventId}find_free_slotsPOST /v1/integrations/{id}/availabilitycreate_calendar_eventPOST /v1/integrations/{id}/eventsZůstatek
get_balanceGET /v1/balanceČísla
get_numberGET /v1/numbers/{e164}join_number_waitlistPOST /v1/numbers/waitlistleave_number_waitlistDELETE /v1/numbers/waitlist/{offerId}get_callback_routingGET /v1/numbers/{e164}/callback-routingset_callback_routingPUT /v1/numbers/{e164}/callback-routingget_sip_statusGET /v1/numbers/{e164}/sip/statuslist_numbersGET /v1/numberssearch_available_numbersGET /v1/numbers/availablebuy_numberPOST /v1/numbersfind_number_addressGET /v1/numbers/address-optionsorder_number_from_regionPOST /v1/numbers/orderslist_number_ordersGET /v1/numbers/orderscancel_number_orderPOST /v1/numbers/orders/{id}/cancelset_number_routingPATCH /v1/numbers/{e164}get_sip_credentialsGET /v1/numbers/{e164}/sipSMS
send_smsPOST /v1/messageslist_messagesGET /v1/messageslist_sms_numbersGET /v1/sms-numbersbuy_sms_numberPOST /v1/sms-numbersHovory
make_callPOST /v1/callslist_callsGET /v1/callsget_callGET /v1/calls/{id}annotate_callPATCH /v1/calls/{id}Hlasy
list_voicesGET /v1/voicesAgenti
create_agentPOST /v1/agentslist_agentsGET /v1/agentsget_agentGET /v1/agents/{id}get_agent_call_holdGET /v1/agents/{id}/call-holdstop_agent_callsPOST /v1/agents/{id}/call-holdupdate_agentPATCH /v1/agents/{id}delete_agentDELETE /v1/agents/{id}test_callPOST /v1/agents/{id}/test-callKoncepty
rollback_agent_draftPOST /v1/agents/{id}/draft/rollbackreconcile_agent_draft_operationPOST /v1/agents/{id}/draft/operationget_agent_draftGET /v1/agents/{id}/draftsave_agent_draftPUT /v1/agents/{id}/draftpublish_agent_draftPOST /v1/agents/{id}/draft/publishsimulate_agent_draftPOST /v1/agents/{id}/simulateNástroje
list_toolsGET /v1/toolstest_toolPOST /v1/tools/testPOST /v1/tools/{id}/testcreate_toolPOST /v1/toolsupdate_toolPATCH /v1/tools/{id}delete_toolDELETE /v1/tools/{id}Webhooky
remove_webhookDELETE /v1/webhooklist_webhook_deliveriesGET /v1/webhook/deliveriesget_webhookGET /v1/webhookset_webhookPUT /v1/webhooksend_test_webhookPOST /v1/webhook/testRelay
create_relay_leasePOST /v1/relaylist_relay_leasesGET /v1/relaycancel_relay_leaseDELETE /v1/relay/{id}Seznam nevolat
add_to_dncPOST /v1/dnclist_dncGET /v1/dncremove_from_dncDELETE /v1/dnc/{e164}unblock_destinationPOST /v1/dnc/{e164}/unblockChangelog
get_changelogGET /v1/changelogÚkoly
list_tasksGET /v1/tasksget_taskGET /v1/tasks/{id}create_taskPOST /v1/tasksupdate_taskPATCH /v1/tasks/{id}pause_taskPOST /v1/tasks/{id}/pauseresolve_task_itemPOST /v1/tasks/{id}/items/{itemId}/resolvereconcile_taskPOST /v1/tasks/{id}/reconcilestart_taskPOST /v1/tasks/{id}/startKredit
list_ledgerGET /v1/credit/ledgercreate_topup_linkPOST /v1/credit/topupget_auto_topupGET /v1/credit/auto-topupdisable_auto_topupPATCH /v1/credit/auto-topupNa klíč
create_setup_orderPOST /v1/setup-orderslist_setup_ordersGET /v1/setup-ordersget_setup_orderGET /v1/setup-orders/{id}message_setup_orderPOST /v1/setup-orders/{id}/messagescheckout_setup_orderPOST /v1/setup-orders/{id}/checkoutlaunch_setup_orderPOST /v1/setup-orders/{id}/launchcancel_setup_orderPOST /v1/setup-orders/{id}/cancelFakturační údaje
list_billing_documentsGET /v1/billing/documentsget_billing_documentGET /v1/billing/documents/{id}create_agent, update_agent, publish_agent_draft a rollback_agent_draft uloží (respektive publikují) agenta i s první větou, která nesděluje, že mluví digitální asistent (evropský AI Act, čl. 50), nebo je odhadem delší než 7 sekund toho, co volající SKUTEČNĚ SLYŠÍ - první věta plus věta o nahrávání, když je recordCalls zapnuté (asi 2,53 slova za sekundu) - nic z toho tím neblokují, jen upozorní; nezměněná výchozí šablona první věty tenhle druhý kód nikdy nespustí. rollback_agent_draft vrací warnings stejně jako publish_agent_draft, protože taky propisuje první větu na živého agenta. Odpověď pak v textu nese větu „Warning: ...“ (MCP odpovídá vždy anglicky) a strojově čitelně kódy first_message_no_ai_disclosure a/nebo first_message_too_long v structuredContent.warnings. Agent s fázemi (pole workflow) přidává do stejného pole další kódy stejně jako portálový editor - dead_end, empty_node, entry_phrase_never_spoken, missing_enter_phrase, short_condition, condition_about_agent, base_prompt_long, workflow_not_synced_to_provider, workflow_node_tool_not_synced (nástroj přiřazený jen fázi se k agentovi na ElevenLabs zatím nepřenáší) a workflow_node_tool_missing (uzel odkazuje nástroj, který na účtu už není - smazaný; fázi je potřeba uložit bez něj) - žádný z nich uložení neblokuje. Základní prompt agenta s fázemi by měl nést i dvě věty, bez kterých agent nejčastěji odpoví, co neví: „Provozní údaje, které nemáš v zadání (otevírací doba, lhůty, ceny, dostupnost lidí), neříkej a neodhaduj - řekni, že to upřesní kolega.“ a „Ptej se vždy jen na jednu věc najednou.“ Varování, které patří konkrétní fázi nebo přechodu, nese navíc nodeId, nebo edgeId. Tvar pole workflow, limity a rozepsaný příklad jsou na /docs/api v sekci Fáze hovoru (workflow). Hovor takového agenta navíc nese workflowPath (get_call, list_calls) - cestu přes uzly - ale jen když ho vyřídil vlastní hlasový motor volai (provider: "engine"); u agenta na ElevenLabs pole nikdy nepřijde, i když fázemi prošel. Samostatný kód calendar_pending_engine_switch se objeví, když má agent nastavený calendar (termíny podle kalendáře), ale běží na ElevenLabs - nastavení se uloží a začne fungovat, jakmile agent přejde na vlastní motor volai. Agent s připojeným číslem, jehož zadání používá proměnnou mimo sadu, kterou příchozí hovor doopravdy dodává, dostane prompt_variables_unavailable_inbound (na příchozím hovoru se dosadí jako prázdný text); první věta, ve které po odstranění všech {{...}} bloků nezůstane žádné písmeno ani číslice mimo proměnné, dostane first_message_empty - ani jeden kód uložení neblokuje. Samostatný kód agent_misuse_suspected (create_agent, update_agent, publish_agent_draft, rollback_agent_draft, save_agent_draft, simulate_agent_draft, make_call, create_task/update_task a create_tool/update_tool) se objeví, když konfigurace agenta, koncept, popis nástroje, proměnné hovoru, název nebo proměnné úkolu nebo prompt zkušebního hovoru obsahuje formulace vydávající se za úřad či jinou instituci, nebo žádající citlivé údaje - viz Podmínky volai § 10; jde jen o upozornění, nic neblokuje. Jen create_agent navíc vrací elevenlabs_by_explicit_choice, když dostal useForOutboundTasks: false u jazyka, kterému by nasazení jinak dalo vlastní motor volai (dnes cs a sk), a agent proto zůstal na ElevenLabs bez hlasů a funkcí motoru; agenta jen na příchozí hovory zakládej bez toho pole.
Nástroje agenta jsou dva kroky, ne jeden
create_tool nástroj jen založí - žádnému agentovi ho sám nezapne. Teprve update_agent s toolIds mu ho přiřadí, a pole se posílá VŽDY CELÉ: co v něm nepošleš, agent po úpravě mít nebude. Týž nástroj může používat víc agentů, patří účtu.
Zvuk nahrávky přes MCP nechodí. get_call řekne polem hasRecording, jestli nahrávka je, a samotnou nahrávku stáhneš stejným API klíčem z GET /v1/calls/{id}/recording - formát určuje hlavička content-type odpovědi: u agenta na ElevenLabs audio/mpeg (MP3), u agenta na motoru volai dnes audio/ogg. Binární tělo v odpovědi MCP nástroje nemá co dělat.
Bezpečná úprava agenta je taky dva kroky, ne jeden: get_agent_draft -> save_agent_draft -> volitelně simulate_agent_draft -> publish_agent_draft. Uložení konceptu nikdy nemění běžícího agenta - živě se projeví až publish_agent_draft. Pro okamžitou změnu bez mezikroku zůstává update_agent.
Co MCP záměrně neumí
V MCP schválně chybí víc věcí, ne jedna - všechny tam, kde by hrozila škoda z jedné špatně pochopené věty nebo z prompt injection. Uvolnění zakoupeného čísla (DELETE /v1/numbers/{e164}) a SMS čísla (DELETE /v1/sms-numbers/{e164}) je v REST API i v portálu, ale ne mezi MCP nástroji - nevratná akce. Stejně schválně chybí odpojení připojené integrace nebo karty, zapnutí či nastavení automatického dobíjení a zápis do e-mailových upozornění (get_account je nese jen ke čtení). Odvolání API klíče v MCP není vůbec - list_api_keys klíče jen vypisuje; odvolat lze jen VLASTNÍ klíč, a to přes REST DELETE /v1/api-keys/{id}, cizí klíč jen v portálu. Přihlašovací údaje k Apple Kalendáři nebo ABRA FlexiBee (POST /v1/integrations) MCP taky nesbírá.
Detail jedné SMS nemá vlastní nástroj, protože by nic nepřidal - list_messages vrací stejná pole jako detailový endpoint. Výdej samotné nahrávky (binární tělo, GET /v1/calls/{id}/recording) taky nemá MCP nástroj - get_call řekne jen hasRecording.
Zkušební hovor bez vlastního čísla je něco jiného a vlastní podporu v make_call má: parametr systemPrompt zavolá ze sdíleného demo čísla volai bez nákupu čísla a bez zakládání agenta. Zkušební hovor OD VLASTNÍHO agenta má od téhle vlny svůj vlastní nástroj test_call - stejný hovor a stejná cena jako make_call s agentId, jen s přísnějším společným denním stropem 3 hovorů na účet napříč všemi agenty.
Vytvoření nového API klíče zůstává jen v portálu (/api-a-mcp), protože klíč, který razí další klíče, by mohl ze ztráty jednoho udělat trvalý přístup. Daňové doklady vznikají automaticky po zaplaceném dobití a MCP je umí číst přes list_billing_documents a get_billing_document; samotné PDF se stahuje jen přes REST. Fakturační adresu a firemní údaje (IČO, DIČ) lze změnit přes update_billing_details.
U konceptu agenta MCP od téhle vlny nástroj pro potvrzení nejisté operace MÁ (reconcile_agent_draft_operation, protějšek REST POST .../draft/operation). Kompletní přehled doručení webhooku (posledních 50, ne jen get_webhook) má taky svůj nástroj - list_webhook_deliveries.
Chyby
MCP nemá HTTP status. Neúspěch nástroje poznáš z isError: true; text výsledku začíná Request error:, Account error:, Busy: nebo volai service error: a structuredContent.error nese stejná pole jako REST: code, cause, message, action, requestId, docsUrl (u konceptu agenta i currentRevision).
cause říká, kdo chybu opraví: request = argumenty nástroje (oprav a zavolej znovu), account = stav účtu zákazníka (kredit, limity, vlastnictví, ověření, neexistující záznam, pozastavení provozovatelem), busy = zámek nebo limit okamžiku (počkej a zopakuj beze změny), service = volai nebo dodavatel (zkus za chvíli, requestId pro podporu). Agent má zákazníkovi říct totéž a nikdy nehlásit request, account ani busy jako výpadek volai.
Tabulka příčin je v dokumentaci REST API v sekci Formát chyb.
Text, který obsahuje Input validation error: Invalid arguments for tool (klient ho většinou ukáže za MCP error -32602:), vzniká v MCP SDK ještě před spuštěním nástroje - argumenty mají špatný tvar. Vždy znamená cause: request, structuredContent u něj chybí a znění pochází z validátoru schématu. Chybějící nebo neplatný API klíč není chyba nástroje: server odpoví HTTP 401 ještě před nástrojem a klíč se opravuje v konfiguraci MCP klienta.
Kde MCP funguje
MCP server volai je obyčejný HTTP transport s hlavičkou Authorization: Bearer vk_... - funguje všude, kde editor umí tenhle základ. Tabulka níž tvrdí jen to, co jsme sami ověřili, s datem.
| Klient | HTTP transport | Vlastní hlavička |
|---|---|---|
| Claude Code | ano | ano |
| Codex CLI | ano | ano |
| Codex desktop | ano | ano |
| Cursor | ano | ano |
| Windsurf | ano | ano |
| VS Code (Copilot) | ano | ano |
| Claude Desktop | ano (přes mcp-remote) | ano |
| n8n | ano (MCP node) | ano (MCP node) |
Tvary konfigurací ověřeny 6. 9. 2026; příkaz pro Claude Code a OAuth čtení přes Codex CLI byly znovu ověřeny 11. 9. 2026. Desktopový postup je dokumentovaný, ruční ověření ještě probíhá.
Webové konektory Claude a ChatGPT se mohou přihlásit přes OAuth na https://volai.cz/mcp. Klient načte /.well-known/oauth-protected-resource/mcp, zaregistruje OAuth klienta a otevře souhlas. Dostupnost vlastních konektorů závisí na tarifu a pravidlech organizace.
Co si editor o nástroji přečte předem
Každý nástroj o sobě hlásí, jak se chová - editor podle toho pozná, kdy se má zeptat a kdy smí jednat sám. Není to bezpečnostní hranice (tu drží kredit, limity a seznam nevolat na naší straně), ale je to důvod, proč se tě dobrý klient zeptá dřív, než smaže agenta:
| Vlastnost | Co znamená |
|---|---|
readOnlyHint | Nástroj nic nemění a nic nestojí - všechna list_* a get_*, a navíc search_available_numbers, find_number_address a propose_calendar_update (ten změnu jen připraví, nezapisuje ji). |
destructiveHint | Přepis existujících dat, zásah do provozu nebo nevratný vedlejší efekt: například update_agent, publish_agent_draft, send_sms, make_call, remove_webhook, nákup čísla, mazání a rušení ochrany. Klient má před takovou akcí získat souhlas uživatele. |
idempotentHint | Zopakování se stejnými hodnotami nic nepřidá. Placené akce (send_sms, make_call, buy_number, buy_sms_number, order_number_from_region) a vytvářecí akce (create_agent, create_relay_lease, create_tool) ho schválně nemají: druhé volání pošle druhou SMS, strhne druhou částku nebo založí druhý záznam, takže je editor po timeoutu nesmí opakovat sám. |
openWorldHint | Akce sahá ven do telefonní sítě, číselníků operátora nebo připojeného kalendáře, ne jen do záznamů tvého účtu. |
Výsledek každého nástroje navíc chodí dvakrát: jako čitelná věta s JSON blokem a zároveň jako strojově čitelný structuredContent - klient, který ho umí, si data vezme odtud a nemusí je louskat z textu.
Vyzkoušej si
Až budeš mít MCP připojené, zkus editoru napsat některou z těchhle vět (klidně svými slovy - nejde o přesné znění):
- Zavolej mi hned na +420777123456 a zkus roli recepční kavárny - nechci si kvůli tomu zakládat vlastní číslo ani agenta.
- Kup mi telefonní číslo a nastav na něj agenta, který bude brát objednávky na kávu.
- Pošli SMS na +420777123456, že objednávka je hotová k vyzvednutí.
- Vypiš mi posledních 10 hovorů a stručně mi je shrň.
- Zjisti, kolik mi zbývá kreditu, a upozorni mě, jestli je to málo.
- Vytvoř agenta na krátký průzkum spokojenosti a rovnou mi na moje číslo zavolej, ať si to vyzkouším.
- Přidej mojí recepční nástroj, který si na mém API ověří stav objednávky, a zapni ho jí.
- Ať si agent z každého hovoru zapíše jméno volajícího a jestli věc spěchá.
Bezpečnost
MCP připojíš přes přihlášení volai a výslovný souhlas (OAuth), nebo ručně stejným API klíčem jako REST API. Obě varianty dovolují číst účet i provádět akce včetně placených hovorů a SMS. Přístup AI aplikace odvoláš na stránce AI asistent; klíče spravuješ v sekci Přístupy a API na téže stránce.
Zacházej s klíčem jako s heslem
Nikdy ho nedávej do frontendového kódu, do repozitáře na GitHubu ani nikomu neposílej v čistém textu. Když ho někdo jiný uvidí, může utratit tvůj kredit, dokud nedojde.
Podezření na únik (nebo jen chuť klíč vyměnit) řeší jedno tlačítko: na stránce AI asistent otevři sekci Přístupy a API a klíč smaž - přestane fungovat okamžitě a nejde obnovit. Vytvoř si nový a aktualizuj ho v konfiguraci editoru.
Související
REST API
Kompletní reference všech endpointů: čísla, hovory, SMS, agenti a jejich koncepty, nástroje, nahrávky, webhooky, seznam nevolat, relay, účet, úkoly, kredit, doklady, kalendáře a integrace.
Hlasový agent
Systémový prompt, nástroje, přepojení na člověka, nahrávky a zapsané údaje z hovoru.
Webhooky
Události, zapsané údaje v těle, ověření podpisu, opakování při chybě.
Vlastní agent
Napojení cizí platformy (ElevenLabs, Asterisk...) - bez agentní přirážky.