Používajte ThunderPhone ako server MCP

Vytvárajte, testujte, overujte a prevádzkujte hlasových agentov ThunderPhone z Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code alebo iného klienta Streamable HTTP MCP.

ThunderPhone poskytuje server Streamable HTTP Model Context Protocol na adrese:

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

Ide o opačný smer než pri pripojení vzdialeného servera MCP k hlasovému agentovi:

Overenie#

Pre klientov využívajúcich adresár predvolene použite OAuth: prihláste sa, vyberte organizáciu a schváľte požadované oprávnenia. Prístup odvoláte v časti Organizácia → Kľúče API → Autorizované aplikácie.

Pre klientov nakonfigurovaných s kľúčom API vytvorte kľúč sk_live_ v časti Organizácia → Kľúče a sprístupnite ho klientovi MCP ako THUNDERPHONE_API_KEY. Kľúč je viazaný na jednu organizáciu; ID patriace inej organizácii sa správa ako nenájdené.

Alternatívy CLI a stdio#

CLI ThunderPhone môže zapísať konfiguráciu klienta so zachovaním nesúvisiacich serverov:

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

Po globálnej inštalácii @thunderphone/mcp použite thunderphone-mcp setup s rovnakými možnosťami. Nastavenie podporuje Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop a Windsurf. Uprednostňuje sa priame HTTP; Desktop používa stdio.

Pre každého klienta podporujúceho stdio nakonfigurujte command: "npx" s args: ["-y", "@thunderphone/mcp"]. Obal najprv používa THUNDERPHONE_API_KEY, potom prihlasovacie údaje z príkazu thunderphone login, pričom obnovuje expirované tokeny, a následne OAuth prostredníctvom mcp-remote. Prihlásenie zariadenia a OAuth vyžadujú príslušné zavedenie OAuth API. Cesta s kľúčom API ho nevyžaduje. Priame konfigurácie HTTP nečítajú úložisko prihlasovacích údajov CLI; na opätovné použitie prihlásenia zariadenia použite obal stdio.

Ide o alternatívy k manuálnym konfiguráciám klienta uvedeným nižšie.

Konfigurácia klienta#

Claude a ChatGPT sa prihlasujú cez OAuth; nepoužíva sa žiadny kľúč API. Ak ešte nemáte účet ThunderPhone, na prihlasovacej stránke vyberte Vytvoriť účet a po overení e-mailu sa vrátite na obrazovku schválenia.

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

1. Otvorte Prispôsobiť → Konektory (v starších verziách Nastavenia → Konektory). Ak sa ThunderPhone zobrazuje v adresári konektorov, vyberte ho. V opačnom prípade vyberte Pridať vlastný konektor, pomenujte ho ThunderPhone a zadajte https://api.thunderphone.com/v1/mcp.
2. Vyberte Pripojiť, prihláste sa do ThunderPhone, vyberte organizáciu a schváľte povolenia.
3. V chate zapnite ThunderPhone v ponuke nástrojov a požiadajte o to, čo potrebujete, napríklad „Zobraziť zoznam mojich agentov“.

Claude sa pred prvým použitím každého nástroja opýta na potvrdenie. Ak chcete väčšinu týchto výziev preskočiť, otvorte Prispôsobiť → Konektory → ThunderPhone a nastavte Nástroje len na čítanie na vždy povoliť. Tieto nástroje iba vyhľadávajú informácie: agentov, hovory, prepisy, zostatky, dokumentáciu. Ak chcete vidieť každú zmenu pred jej vykonaním, ponechajte pri Nástrojoch na zápis/odstránenie možnosť schválenia.

Vlastné konektory vyžadujú platený plán Claude. Pri plánoch Team a Enterprise vlastník najprv pridá konektor v nastaveniach konektorov organizácie a potom si každý člen pripojí vlastný účet ThunderPhone.

ChatGPT#

1. Ak sa ThunderPhone zobrazuje v adresári aplikácií ChatGPT, vyberte ho a pripojte sa.
2. V opačnom prípade otvorte Nastavenia → Aplikácie a konektory → Rozšírené nastavenia, zapnite Režim vývojára a vytvorte konektor s adresou URL https://api.thunderphone.com/v1/mcp a autentifikáciou OAuth.
3. Prihláste sa do ThunderPhone, vyberte organizáciu a schváľte povolenia. Pridajte ThunderPhone do chatu z ponuky nástrojov.

Odstránenie agenta alebo telefónneho čísla, zahodenie konceptu, spustenie kampane a odoslanie testovacej požiadavky, ktorá môže zapisovať do externého systému, vyžadujú v oboch aplikáciách druhé potvrdenie; pozrite si časť Potvrdzovanie deštruktívnych akcií.

Claude Code#

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

Codex#

Pridajte toto do ~/.codex/config.toml:

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

Cursor#

Vytvorte .cursor/mcp.json:

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

Claude Desktop#

Pridajte most mcp-remote do konfigurácie 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#

Vytvorte .vscode/mcp.json a zadajte kľúč prostredníctvom výzvy na zadanie vo 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 anotácie MCP. V tabuľkách R znamená iba na čítanie, D deštruktívny, I idempotentný a O interakciu s otvoreným svetom alebo sieťou. Pomlčka znamená, že nie je nastavená žiadna nápoveda.

Pripojenie#

Agenti#

Telefónne čísla a operátori#

SMS#

Hovory#

Testovanie a overovanie#

Znalosti#

Integrácie, webhooky a vzdialené servery MCP#

Kampane#

Hlasy, fakturácia a dokumentácia#

Všetky produktové nástroje používajú rovnaké kódové cesty REST ako verejné API. Overovanie REST, rozsah organizácie, roly, schvaľovanie fakturácie, kvóty, potvrdenie TCPA, bezpečnosť poskytovateľov a správanie auditu sa preto uplatňujú bez zmeny.

Potvrdzovanie deštruktívnych akcií#

Nástroje označené D niečo menia alebo odstraňujú, prípadne začínajú vytáčať skutočných ľudí. Tie, ktoré nemožno vrátiť späť, vyžadujú dve požiadavky. Prvá požiadavka nič nezmení a vráti:

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

Asistent používateľovi zobrazí, čo bude ovplyvnené, a požiada o potvrdenie. Potom požiadavku zopakuje s rovnakými argumentmi a navyše s confirmation_token. Token je platný 10 minút a vzťahuje sa na jednu organizáciu, jeden nástroj a jednu presnú množinu argumentov, takže odstránenie troch agentov vyžaduje tri potvrdenia. campaign_action s pause alebo stop tento krok preskočí, aby bolo možné prebiehajúcu kampaň vždy okamžite zastaviť, rovnako ako test_integration s GET. Niektoré nástroje D sa spúšťajú jednou požiadavkou, pretože D označuje ich účinok, nie potvrdenie na strane servera: update_agent nahradí obsah konceptu (discard_agent_draft ho vráti späť), deploy_agent nahradí aktívnu konfiguráciu, update_phone_number presmeruje aktívne hovory, sync_mcp_server_tools nahradí katalóg nástrojov vzdialeného servera, import_voip_numbers zmení smerovanie čísel k vášmu operátorovi, run_agent_tests môže minúť kredit, send_sms a place_call kontaktujú skutočnú osobu (place_call si zachováva vlastné potvrdenie súhlasu) a provision_phone_number zakúpi číslo. Váš klient MCP vás môže stále požiadať o ich schválenie.

Úvodné prompty#

prompts/list ponúka päť opakovane použiteľných pracovných postupov:

• create_inbound_receptionist
• run_agent_tests
• buy_and_attach_number
• review_low_grade_calls
• add_url_to_agent_knowledge

Pomocou prompts/get s uvedeným názvom promptu a jeho deklarovanými argumentmi získate správu používateľa pripravenú na spustenie.

Zdroje#

resources/list sprístupňuje verejné referencie uložené vo vyrovnávacej pamäti:

Jeden zdroj načítate pomocou resources/read. Verejné načítania používajú krátky časový limit, limit 2 MiB a desaťminútovú vyrovnávaciu pamäť v procese.

Protokol a chyby#

Server podporuje verzie protokolu 2025-06-18 a 2025-03-26; zopakuje podporovanú verziu klienta a v opačnom prípade vyberie 2025-06-18. Implementuje initialize, ping, nástroje, prompty, zdroje a notifikácie. Notifikácie vracajú 202 Accepted. Tento bezstavový server neposkytuje SSE listener ani odstránenie relácie, preto GET a DELETE vracajú 405 Method Not Allowed s Allow: POST.

Zlyhania nástrojov zostávajú úspešnými odpoveďami JSON-RPC s isError: true. Ich text obsahuje krátku vetu, po ktorej nasleduje blok JSON:

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

Pre place_call zostáva zachovaná odlišná predpona outbound_tcpa_confirmation_required:. Neznáme metódy JSON-RPC vracajú -32601 v odpovedi HTTP 200. Dávky JSON-RPC nie sú podporované v MCP 2025-06-18 a vracajú jasnú chybu neplatnej požiadavky -32600.