Open in

Používejte ThunderPhone jako server MCP

Vytvářejte, testujte, ověřujte a provozujte hlasové agenty ThunderPhone z Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code nebo jiného klienta Streamable HTTP MCP.

ThunderPhone poskytuje server Streamable HTTP Model Context Protocol na adrese:

https://api.thunderphone.com/v1/mcp

Jde o opačný směr než při připojení vzdáleného serveru MCP k hlasovému agentovi:

Směr	Výsledek
Vzdálený server MCP → agent ThunderPhone	Hlasový agent může volat nástroje vzdáleného serveru.
ThunderPhone → váš klient MCP	Váš programovací agent může ThunderPhone vytvářet, testovat a provozovat.

Ověření

Pro klienty z adresáře ve výchozím nastavení použijte OAuth: přihlaste se, vyberte organizaci a schvalte požadovaná oprávnění. Přístup odeberte v části Organizace → Klíče API → Autorizované aplikace.

Pro klienty nakonfigurované pomocí klíče API vytvořte klíč sk_live_ v části Organizace → Klíče a zpřístupněte jej klientovi MCP jako THUNDERPHONE_API_KEY. Klíč je vázán na jednu organizaci; ID vlastněné jinou organizací se chová, jako by nebylo nalezeno.

Alternativy CLI a stdio

Rozhraní ThunderPhone CLI může zapsat konfiguraci klienta a zároveň zachovat nesouvisející servery:

npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user

Po globální instalaci @thunderphone/mcp použijte thunderphone-mcp setup se stejnými možnostmi. Nastavení podporuje Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop a Windsurf. Upřednostňuje se přímé HTTP; Desktop používá stdio.

Pro libovolného klienta podporujícího stdio nakonfigurujte command: "npx" s args: ["-y", "@thunderphone/mcp"]. Obal nejprve používá THUNDERPHONE_API_KEY, poté přihlašovací údaje z thunderphone login, obnovuje tokeny po vypršení platnosti a následně OAuth prostřednictvím mcp-remote. Přihlášení zařízení a OAuth vyžadují odpovídající zavedení OAuth rozhraní API. Cesta s klíčem API jej nevyžaduje. Konfigurace přímého HTTP nečtou úložiště přihlašovacích údajů CLI; pro opětovné použití přihlášení zařízení použijte obal stdio.

Jedná se o alternativy k ručním konfiguracím klientů níže.

Konfigurace klienta

Claude a ChatGPT se přihlašují pomocí OAuth; žádný klíč API se nepoužívá. Pokud ještě nemáte účet ThunderPhone, na přihlašovací stránce zvolte Vytvořit účet a po ověření e-mailu se vrátíte na obrazovku schválení.

Claude (web, počítač a mobil)

Otevřete Přizpůsobit → Konektory (ve starších verzích Nastavení → Konektory). Pokud se ThunderPhone zobrazí v katalogu konektorů, vyberte jej. Jinak zvolte Přidat vlastní konektor, pojmenujte jej ThunderPhone a zadejte https://api.thunderphone.com/v1/mcp.
Vyberte Připojit, přihlaste se do ThunderPhone, vyberte organizaci a schvalte oprávnění.
V chatu zapněte ThunderPhone v nabídce nástrojů a požádejte o to, co potřebujete, například „Vypiš moje agenty“.

Claude se před prvním použitím každého nástroje zeptá na potvrzení. Chcete-li většinu těchto výzev přeskočit, otevřete Přizpůsobit → Konektory → ThunderPhone a u možnosti Nástroje jen pro čtení nastavte vždy povolit. Tyto nástroje pouze vyhledávají informace: agenty, hovory, přepisy, zůstatky a dokumentaci. Pokud chcete vidět každou změnu před jejím provedením, ponechte u Nástrojů pro zápis/odstranění vyžadování schválení.

Vlastní konektory vyžadují placený tarif Claude. U tarifů Team a Enterprise vlastník nejprve přidá konektor v nastavení konektorů organizace a poté si každý člen připojí vlastní účet ThunderPhone.

ChatGPT

Pokud se ThunderPhone zobrazí v katalogu aplikací ChatGPT, vyberte jej a připojte.
Jinak otevřete Nastavení → Aplikace a konektory → Pokročilá nastavení, zapněte Režim pro vývojáře a vytvořte konektor s adresou URL https://api.thunderphone.com/v1/mcp a ověřováním OAuth.
Přihlaste se do ThunderPhone, vyberte organizaci a schvalte oprávnění. Přidejte ThunderPhone do chatu z nabídky nástrojů.

Odstranění agenta nebo telefonního čísla, zahození konceptu, spuštění kampaně a odeslání testovacího požadavku, který může zapisovat do externího systému, vyžadují v obou aplikacích druhé potvrzení; viz Potvrzování destruktivních akcí.

Claude Code

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex

Přidejte toto do ~/.codex/config.toml:

[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"

Cursor

Vytvořte .cursor/mcp.json:

{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Claude Desktop

Přidejte most mcp-remote do konfigurace Claude Desktop:

{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

VS Code

Vytvořte .vscode/mcp.json a zadejte klíč prostřednictvím výzvy k zadání ve VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}

Nástroje

Každý nástroj obsahuje anotace MCP. V tabulkách R znamená pouze pro čtení, D destruktivní, I idempotentní a O interakci s externím světem nebo sítí. Pomlčka znamená, že není nastavena žádná nápověda.

Připojení

Nástroj	Hlavní argumenty	Anotace	Co dělá
`get_connection_identity`	—	R, I	Ověří přihlašovací údaje a vrátí organizaci a bezpečná metadata přihlašovacích údajů.

Agenti

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_agents`	—	R, I	Vypíše agenty.
`get_agent`	`agent_id`	R, I	Získá jednoho agenta.
`create_agent`	konfigurace agenta	—	Vytvoří agenta.
`update_agent`	`agent_id`, změněná pole	D	Uloží pole do konceptu agenta a nahradí tím, co koncept obsahoval. Spustí se bez kroku potvrzení: nasazený agent zůstane nezměněn až do `deploy_agent` a `discard_agent_draft` vrátí koncept zpět.
`deploy_agent`	`agent_id`, volitelné `if_updated_at`	D, I	Povýší koncept do produkce.
`discard_agent_draft`	`agent_id`, volitelné `if_updated_at`, `confirmation_token` při druhém požadavku	D, I	Zahodí připravené změny. Dvoufázové, viz Potvrzování destruktivních akcí.
`duplicate_agent`	`agent_id`, volitelné `name`	—	Zkopíruje agenta v rámci organizace.
`delete_agent`	`agent_id`, `confirmation_token` při druhém požadavku	D, I	Trvale odstraní agenta. Dvoufázové.
`list_agent_versions`	`agent_id`	R, I	Vypíše nasazené verze konfigurace.

Telefonní čísla a operátoři

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_phone_numbers`	—	R, I	Vypíše čísla organizace a směrování.
`get_phone_number_limits`	—	R, I	Získá využití a limity spravovaných čísel.
`provision_phone_number`	volitelné `area_code`, `city`, `state`, `idempotency_key`	D, O	Zakoupí příchozí číslo spravované službou ThunderPhone.
`list_voip_connections`	—	R, I	Vypíše připojené operátory zákazníka.
`search_voip_numbers`	`connection_id`, `country`, `type`, volitelné `area_code`	R, I, O	Vyhledá v inventáři operátora.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Importuje čísla, která již vlastníte u operátora.
`update_phone_number`	`phone_number_id`, pole směrování/popisku/webhooku	D	Aktualizuje směrování čísla včetně přiřazení agenta.
`delete_phone_number`	`phone_number_id`, `confirm`, volitelné `release_at_provider`, `confirmation_token` při druhém požadavku	D, I, O	Uvolní číslo. Dvoukrokové.

SMS

Nástroj	Hlavní argumenty	Anotace	Co dělá
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Odešle jednu textovou SMS prostřednictvím připojeného čísla Twilio nebo Telnyx.

Hovory

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_calls`	volitelné filtry, `limit`, `offset`	R, I	Vypíše hovory s použitím filtrů historie hovorů REST.
`get_call`	`call_id`	R, I	Získá stav hovoru a metadata.
`get_call_transcript`	`call_id`, volitelný `live`	R, I	Získá přepis hovoru.
`get_call_audio_url`	`call_id`, volitelný `download`	R, I, O	Vrátí podepsanou adresu URL zvuku; zvuk nikdy nestreamuje prostřednictvím MCP.
`get_call_grade`	`call_id`	R, I	Získá nejnovější hodnocení hovoru.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Zahájí jeden neidempotentní odchozí hovor.
`export_calls`	filtry hovorů, `export_format`	R, I	Exportuje až do limitu koncového bodu REST ve formátu JSON nebo CSV.

Testování a ověřování

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_test_scenarios`	`agent_id`	R, I	Vypíše testovací scénáře.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, volitelné podmínky	—	Vytvoří scénář.
`generate_test_scenarios`	`agent_id`, volitelné `count`, `include_edge_cases`, `locale`	O	Vygeneruje scénáře z promptu agenta.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, volitelný výběr/matice	D, O	Spustí scénáře přes web nebo telefonii.
`get_test_run`	`agent_id`, `batch_id`	R, I	Získá stav dávky a výsledky jednotlivých scénářů.
`list_validation_runs`	`agent_id`	R, I	Vypíše nedávná spuštění ověření konceptu.
`get_validation_status`	`agent_id`	R, I	Získá nejnovější stav ověření a shodu konceptu.

Znalosti

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_knowledge_bases`	—	R, I	Vypíše znalostní báze.
`create_knowledge_base`	`name`, volitelné `description`	—	Vytvoří znalostní bázi.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Přidá text nebo Markdown.
`import_knowledge_url`	`url`, volitelné `name`	O	Zařadí veřejnou stránku do fronty pro bezpečné zpracování.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Vyhledá v produkčním získávání informací.

Integrace, webhooky a vzdálené servery MCP

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_integrations`	—	R, I	Vypíše integrace funkcí HTTP.
`create_integration`	`display_name`, specifikace funkce `spec`, volitelná pole koncového bodu	—	Vytvoří nástroj HTTP. Hlavičky ověřování přidejte v ovládacím panelu.
`test_integration`	`url`, volitelná metoda/tělo/časový limit, `integration_id` s `header_names`, `confirmation_token` při druhém požadavku	D, O	Odešle omezený testovací požadavek chráněný proti SSRF. Uložené hodnoty hlaviček se doplní z integrace a odešlou se pouze jejímu vlastnímu hostiteli. `POST` (výchozí), `PUT`, `PATCH` a `DELETE` jsou dvoukrokové; `GET` se spustí okamžitě.
`list_webhook_endpoints`	—	R, I	Vypíše podepsané koncové body webhooků.
`list_webhook_deliveries`	volitelné `agent_id`, volitelné `endpoint_id`	R, I	Vypíše nedávné výsledky doručení webhooků bez datových částí.
`create_webhook_endpoint`	`label`, `url`, volitelné události/stav	O	Vytvoří podepsaný koncový bod webhooku.
`test_webhook_endpoint`	`endpoint_id`	O	Odešle syntetickou událost prostřednictvím běžného doručení.
`list_mcp_servers`	—	R, I	Vypíše vzdálené servery, které mohou volat hlasoví agenti.
`create_mcp_server`	`display_name`, `url`	O	Zaregistruje a synchronizuje vzdálený server. Servery, které vyžadují ověřovací hlavičky, přidejte v ovládacím panelu.
`sync_mcp_server_tools`	`server_id`	D, O	Obnoví katalog nástrojů vzdáleného serveru.

Kampaně

Nástroj	Hlavní argumenty	Anotace	Co dělá
`list_campaigns`	—	R, I	Vypíše odchozí kampaně.
`create_campaign`	pole kampaně	—	Vytvoří koncept kampaně.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Přidá až 5 000 kontaktů JSON.
`campaign_action`	`campaign_id`, `action`, volitelné `consent_to_charge`, `confirmation_token` při druhém požadavku	D, O	Spustí `start`, `pause`, `resume` nebo `stop`. `start` a `resume` jsou dvoukrokové; `pause` a `stop` se spustí okamžitě.
`get_campaign_stats`	`campaign_id`	R, I	Získá čítače a nedávné výsledky.

Hlasy, fakturace a dokumentace

Nástroj	Hlavní argumenty	Poznámky	Co dělá
`list_voices`	—	R, I	Vypíše hlasy a podporované jazyky.
`preview_voice`	`voice`, `language`, `text`	O	Vygeneruje ukázku a vrátí podepsanou adresu URL.
`list_voice_clones`	—	R, I	Vypíše vlastní klony hlasů.
`get_billing_summary`	—	R, I	Získá zůstatek a závazné ceny tarifních úrovní; neumožňuje žádné změny plateb.
`search_docs`	`query`, volitelný `limit`	R, I, O	Prohledá veřejný index dokumentace.
`get_doc_page`	`path`	R, I, O	Načte jednu veřejnou stránku dokumentace ve formátu Markdown.

Všechny produktové nástroje používají stejné cesty kódu REST jako veřejné API. Ověřování REST, vymezení organizace, role, povolení fakturace, kvóty, potvrzení TCPA, bezpečnost poskytovatelů a chování auditu proto platí beze změny.

Potvrzování destruktivních akcí

Nástroje označené D něco mění nebo odstraňují, případně zahajují vytáčení skutečným lidem. Ty, které nelze vrátit zpět, vyžadují dva požadavky. První požadavek nic nemění a vrátí:

{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}

Asistent uživateli ukáže, čeho se akce týká, a požádá o potvrzení. Poté požadavek zopakuje se stejnými argumenty a přidá confirmation_token. Token je platný 10 minut a vztahuje se na jednu organizaci, jeden nástroj a jednu přesnou sadu argumentů, takže odstranění tří agentů vyžaduje tři potvrzení. campaign_action s pause nebo stop tento krok přeskočí, aby bylo možné probíhající kampaň vždy okamžitě zastavit, stejně jako test_integration s GET. Některé nástroje D se spouštějí jedním požadavkem, protože D označuje jejich účinek, nikoli potvrzení na straně serveru: update_agent nahradí obsah návrhu (discard_agent_draft jej vrátí zpět), deploy_agent nahradí aktivní konfiguraci, update_phone_number přesměruje probíhající hovory, sync_mcp_server_tools nahradí katalog nástrojů vzdáleného serveru, import_voip_numbers přesměruje čísla k vašemu operátorovi, run_agent_tests může spotřebovat kredit, send_sms a place_call kontaktují skutečnou osobu (place_call zachovává vlastní potvrzení souhlasu) a provision_phone_number zakoupí číslo. Váš klient MCP vás přesto může požádat o jejich schválení.

Úvodní prompty

prompts/list nabízí pět znovupoužitelných pracovních postupů:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Pomocí prompts/get s uvedeným názvem promptu a jeho deklarovanými argumenty získáte připravenou uživatelskou zprávu ke spuštění.

Zdroje

resources/list zpřístupňuje veřejné referenční zdroje uložené v mezipaměti:

URI	Obsah
`thunderphone://docs/llms.txt`	Veřejný index dokumentace.
`thunderphone://docs/quickstart`	Markdown pro rychlý začátek.
`thunderphone://pricing`	Aktuální veřejný Markdown s cenami.

Jeden zdroj načtěte pomocí resources/read. Veřejná načítání používají krátký časový limit, limit 2 MiB a desetiminutovou mezipaměť v procesu.

Protokol a chyby

Server podporuje verze protokolu 2025-06-18 a 2025-03-26; vrací podporovanou verzi klienta a v ostatních případech vybere 2025-06-18. Implementuje initialize, ping, nástroje, prompty, zdroje a oznámení. Oznámení vracejí 202 Accepted. Tento bezstavový server nezpřístupňuje posluchač SSE ani odstranění relace, takže GET a DELETE vracejí 405 Method Not Allowed s Allow: POST.

Selhání nástrojů zůstávají úspěšnými odpověďmi JSON-RPC s isError: true. Jejich text obsahuje krátkou větu následovanou blokem JSON:

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

Pro place_call zůstává zachována odlišná předpona outbound_tcpa_confirmation_required:. Neznámé metody JSON-RPC vracejí -32601 v odpovědi HTTP 200. Dávky JSON-RPC nejsou podporovány protokolem MCP 2025-06-18 a vracejí čistou chybu neplatného požadavku -32600.