Open in

Utilizați ThunderPhone ca server MCP

Construiți, testați, validați și operați agenți vocali ThunderPhone din Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code sau alt client MCP Streamable HTTP.

ThunderPhone expune un server Streamable HTTP Model Context Protocol la:

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

Aceasta este direcția opusă față de conectarea unui server MCP la distanță la un agent vocal:

Direcție	Rezultat
Server MCP la distanță → agent ThunderPhone	Un agent vocal poate apela instrumentele serverului la distanță.
ThunderPhone → clientul dumneavoastră MCP	Agentul dumneavoastră de programare poate construi, testa și opera ThunderPhone.

Autentificare

Utilizați OAuth în mod implicit pentru clienții de tip director: autentificați-vă, alegeți o organizație și aprobați permisiunile solicitate. Revocați accesul din Organizație → Chei API → Aplicații autorizate.

Pentru clienții configurați cu o cheie API, creați o cheie sk_live_ din Organizație → Chei și expuneți-o clientului dumneavoastră MCP ca THUNDERPHONE_API_KEY. Cheia este asociată cu o singură organizație; un id deținut de o altă organizație se comportă ca și cum nu ar fi găsit.

Alternative CLI și stdio

ThunderPhone CLI poate scrie configurația clientului păstrând serverele fără legătură:

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

După o instalare globală a @thunderphone/mcp, utilizați thunderphone-mcp setup cu aceleași opțiuni. Configurarea acceptă Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop și Windsurf. HTTP direct este preferat; Desktop utilizează stdio.

Pentru orice client compatibil cu stdio, configurați command: "npx" cu args: ["-y", "@thunderphone/mcp"]. Învelișul utilizează mai întâi THUNDERPHONE_API_KEY, apoi acreditările din thunderphone login, reînnoind tokenurile expirate, apoi OAuth prin mcp-remote. Autentificarea pe dispozitiv și OAuth necesită lansarea OAuth corespunzătoare pentru API. Calea cu cheie API nu necesită aceasta. Configurațiile HTTP directe nu citesc stocarea de acreditări CLI; utilizați învelișul stdio pentru a reutiliza autentificarea pe dispozitiv.

Acestea sunt alternative la configurațiile manuale de client de mai jos.

Configurarea clientului

Claude și ChatGPT se conectează cu OAuth; nu este implicată nicio cheie API. Dacă nu aveți încă un cont ThunderPhone, alegeți Creați un cont pe pagina de conectare, iar după ce vă verificați e-mailul reveniți la ecranul de aprobare.

Claude (web, desktop și mobil)

Deschideți Personalizare → Conectori (Setări → Conectori în versiunile mai vechi). Dacă ThunderPhone apare în directorul de conectori, selectați-l. În caz contrar, alegeți Adăugați conector personalizat, denumiți-l ThunderPhone și introduceți https://api.thunderphone.com/v1/mcp.
Selectați Conectare, conectați-vă la ThunderPhone, alegeți organizația și aprobați permisiunile.
Într-un chat, activați ThunderPhone din meniul de instrumente și solicitați ce aveți nevoie, de exemplu „Afișează-mi agenții”.

Claude vă solicită aprobarea înainte de a utiliza fiecare instrument pentru prima dată. Pentru a omite majoritatea acestor solicitări, deschideți Personalizare → Conectori → ThunderPhone și setați Instrumente doar pentru citire să fie permise întotdeauna. Aceste instrumente doar consultă informații: agenți, apeluri, transcrieri, solduri, documentație. Păstrați Instrumente de scriere/ștergere cu aprobare dacă doriți să vedeți fiecare modificare înainte ca aceasta să fie efectuată.

Conectorii personalizați necesită un abonament Claude plătit. În abonamentele Team și Enterprise, un proprietar adaugă mai întâi conectorul în setările de conectori ale organizației, apoi fiecare membru își conectează propriul cont ThunderPhone.

ChatGPT

Dacă ThunderPhone apare în directorul de aplicații ChatGPT, selectați-l și conectați-vă.
În caz contrar, deschideți Setări → Aplicații și conectori → Setări avansate, activați Mod pentru dezvoltatori și creați un conector cu URL-ul https://api.thunderphone.com/v1/mcp și autentificare OAuth.
Conectați-vă la ThunderPhone, alegeți organizația și aprobați permisiunile. Adăugați ThunderPhone într-un chat din meniul de instrumente.

Ștergerea unui agent sau a unui număr de telefon, anularea unei schițe, lansarea unei campanii și trimiterea unei solicitări de test care poate scrie într-un sistem extern necesită o a doua confirmare în oricare dintre aplicații; consultați Confirmarea acțiunilor distructive.

Claude Code

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

Codex

Adăugați aceasta în ~/.codex/config.toml:

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

Cursor

Creați .cursor/mcp.json:

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

Claude Desktop

Adăugați o punte mcp-remote în configurația 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

Creați .vscode/mcp.json și introduceți cheia prin solicitarea de introducere a datelor din 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}"
      }
    }
  }
}

Instrumente

Fiecare instrument include adnotări MCP. În tabele, R înseamnă doar citire, D distructiv, I idempotent și O interacțiune cu lumea externă/rețeaua. O liniuță înseamnă că nu este setat niciun indiciu.

Conexiune

Instrument	Argumente principale	Adnotări	Ce face
`get_connection_identity`	—	R, I	Validează credențiala și returnează organizația acesteia și metadatele sigure ale credențialei.

Agenți

Instrument	Argumente principale	Anotații	Ce face
`list_agents`	—	R, I	Listează agenții.
`get_agent`	`agent_id`	R, I	Obține un agent.
`create_agent`	configurația agentului	—	Creează un agent.
`update_agent`	`agent_id`, câmpuri modificate	D	Pregătește câmpurile în schița agentului, înlocuind valorile existente în schiță. Se execută fără o etapă de confirmare: agentul publicat rămâne neschimbat până la `deploy_agent`, iar `discard_agent_draft` anulează modificările din schiță.
`deploy_agent`	`agent_id`, `if_updated_at` opțional	D, I	Publică schița în producție.
`discard_agent_draft`	`agent_id`, `if_updated_at` opțional, `confirmation_token` la a doua solicitare	D, I	Anulează modificările pregătite. Proces în doi pași; consultați Confirmarea acțiunilor distructive.
`duplicate_agent`	`agent_id`, `name` opțional	—	Copiază un agent în cadrul organizației.
`delete_agent`	`agent_id`, `confirmation_token` la a doua solicitare	D, I	Șterge definitiv un agent. Proces în doi pași.
`list_agent_versions`	`agent_id`	R, I	Listează versiunile de configurație publicate.

Numere de telefon și operatori

Instrument	Argumente principale	Adnotări	Ce face
`list_phone_numbers`	—	R, I	Listează numerele organizației și rutarea acestora.
`get_phone_number_limits`	—	R, I	Obține utilizarea și limitele pentru numerele gestionate.
`provision_phone_number`	opționale `area_code`, `city`, `state`, `idempotency_key`	D, O	Cumpără un număr de intrare gestionat de ThunderPhone.
`list_voip_connections`	—	R, I	Listează operatorii clientului conectați.
`search_voip_numbers`	`connection_id`, `country`, `type`, opțional `area_code`	R, I, O	Caută în inventarul operatorului.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Importă numere deja deținute la operator.
`update_phone_number`	`phone_number_id`, câmpuri de rutare/etichetă/webhook	D	Actualizează rutarea numărului, inclusiv atribuirea agentului.
`delete_phone_number`	`phone_number_id`, `confirm`, opționale `release_at_provider`, `confirmation_token` la a doua solicitare	D, I, O	Eliberează un număr. Proces în doi pași.

SMS

Instrument	Argumente principale	Adnotări	Ce face
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Trimite un SMS în text simplu printr-un număr Twilio sau Telnyx conectat.

Apeluri

Instrument	Argumente principale	Anotații	Ce face
`list_calls`	filtre opționale, `limit`, `offset`	R, I	Listează apelurile folosind filtrele REST pentru istoricul apelurilor.
`get_call`	`call_id`	R, I	Obține starea și metadatele apelului.
`get_call_transcript`	`call_id`, `live` opțional	R, I	Obține transcrierea apelului.
`get_call_audio_url`	`call_id`, `download` opțional	R, I, O	Returnează un URL audio semnat; nu redă niciodată audio prin MCP.
`get_call_grade`	`call_id`	R, I	Obține cea mai recentă evaluare a apelului.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Efectuează un apel extern ne-idempotent.
`export_calls`	filtre pentru apeluri, `export_format`	R, I	Exportă până la limita endpointului REST ca JSON sau CSV.

Testare și validare

Instrument	Argumente principale	Adnotări	Ce face
`list_test_scenarios`	`agent_id`	R, I	Listează scenariile de testare.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, condiții opționale	—	Creează un scenariu.
`generate_test_scenarios`	`agent_id`, `count` opțional, `include_edge_cases`, `locale`	O	Generează scenarii din promptul agentului.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, selecție/matrice opțională	D, O	Rulează scenarii prin web sau telefonie.
`get_test_run`	`agent_id`, `batch_id`	R, I	Obține starea lotului și rezultatele pentru fiecare scenariu.
`list_validation_runs`	`agent_id`	R, I	Listează rulările recente de validare a schiței.
`get_validation_status`	`agent_id`	R, I	Obține cea mai recentă stare de validare și potrivirea cu schița.

Cunoștințe

Instrument	Argumente principale	Adnotări	Ce face
`list_knowledge_bases`	—	R, I	Listează bazele de cunoștințe.
`create_knowledge_base`	`name`, opțional `description`	—	Creează o bază de cunoștințe.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Adaugă text sau Markdown.
`import_knowledge_url`	`url`, opțional `name`	O	Pune în coadă o pagină publică pentru ingerare sigură.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Caută prin mecanismul de recuperare din producție.

Integrări, webhookuri și servere MCP la distanță

Instrument	Argumente principale	Adnotări	Ce face
`list_integrations`	—	R, I	Listează integrările funcțiilor HTTP.
`create_integration`	`display_name`, `spec` pentru funcție, câmpuri opționale pentru endpoint	—	Creează un instrument HTTP. Adăugați antete de autentificare în tabloul de bord.
`test_integration`	`url`, metodă/corp/limită de timp opționale, `integration_id` cu `header_names`, `confirmation_token` la a doua solicitare	D, O	Trimite o solicitare de test limitată și protejată împotriva SSRF. Valorile salvate ale antetelor sunt preluate din integrare și trimise numai către propriul său gazdă. `POST` (implicit), `PUT`, `PATCH` și `DELETE` necesită doi pași; `GET` rulează imediat.
`list_webhook_endpoints`	—	R, I	Listează endpointurile webhook semnate.
`list_webhook_deliveries`	`agent_id` opțional, `endpoint_id` opțional	R, I	Listează rezultatele recente ale livrărilor webhook fără încărcătură utilă.
`create_webhook_endpoint`	`label`, `url`, evenimente/stare opționale	O	Creează un endpoint webhook semnat.
`test_webhook_endpoint`	`endpoint_id`	O	Trimite un eveniment sintetic prin livrarea normală.
`list_mcp_servers`	—	R, I	Listează serverele la distanță care pot fi apelate de agenți vocali.
`create_mcp_server`	`display_name`, `url`	O	Înregistrează și sincronizează un server la distanță. Serverele care necesită antete de autentificare sunt adăugate în tabloul de bord.
`sync_mcp_server_tools`	`server_id`	D, O	Reîmprospătează catalogul de instrumente al unui server la distanță.

Campanii

Instrument	Argumente principale	Adnotări	Ce face
`list_campaigns`	—	R, I	Listează campaniile de ieșire.
`create_campaign`	câmpurile campaniei	—	Creează o campanie în schiță.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Adaugă până la 5.000 de contacte JSON.
`campaign_action`	`campaign_id`, `action`, opțional `consent_to_charge`, `confirmation_token` la a doua solicitare	D, O	Rulează `start`, `pause`, `resume` sau `stop`. `start` și `resume` sunt în doi pași; `pause` și `stop` rulează imediat.
`get_campaign_stats`	`campaign_id`	R, I	Obține contoarele și rezultatele recente.

Voci, facturare și documentație

Instrument	Argumente principale	Anotații	Ce face
`list_voices`	—	R, I	Listează vocile și limbile acceptate.
`preview_voice`	`voice`, `language`, `text`	O	Generează un eșantion și returnează un URL semnat.
`list_voice_clones`	—	R, I	Listează clonele vocale personalizate.
`get_billing_summary`	—	R, I	Obține soldul și prețurile oficiale ale nivelurilor; nu sunt expuse modificări ale plăților.
`search_docs`	`query`, opțional `limit`	R, I, O	Caută în indexul documentației publice.
`get_doc_page`	`path`	R, I, O	Preia o pagină publică de documentație Markdown.

Toate instrumentele de produs folosesc aceleași căi de cod REST ca API-ul public. Prin urmare, validarea REST, delimitarea la nivel de organizație, rolurile, aprobarea facturării, cotele, confirmarea TCPA, siguranța furnizorilor și comportamentul de audit se aplică fără modificări.

Confirmarea acțiunilor distructive

Instrumentele marcate cu D modifică sau elimină ceva ori încep apelarea unor persoane reale. Cele care nu pot fi anulate necesită două solicitări. Prima solicitare nu modifică nimic și returnează:

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

Asistentul îi arată utilizatorului ce este afectat și solicită confirmarea. Apoi repetă solicitarea cu aceleași argumente, plus confirmation_token. Un token este valabil 10 minute și acoperă o organizație, un instrument și un singur set exact de argumente, astfel că ștergerea a trei agenți necesită trei confirmări. campaign_action cu pause sau stop omite acest pas, astfel încât o campanie în desfășurare să poată fi oprită imediat, la fel ca test_integration cu GET. Unele instrumente D rulează într-o singură solicitare deoarece D le marchează efectul, nu o confirmare pe partea serverului: update_agent înlocuiește conținutul schiței (discard_agent_draft îl revine), deploy_agent înlocuiește configurația activă, update_phone_number redirecționează apelurile active, sync_mcp_server_tools înlocuiește catalogul de instrumente al unui server la distanță, import_voip_numbers redirecționează numerele către operatorul dvs., run_agent_tests poate consuma credit, send_sms și place_call contactează o persoană reală (place_call își păstrează propria confirmare de consimțământ), iar provision_phone_number cumpără un număr. Clientul dvs. MCP vă poate solicita totuși să le aprobați.

Solicitări inițiale

prompts/list oferă cinci fluxuri de lucru reutilizabile:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Utilizați prompts/get cu numele solicitării listate și argumentele declarate ale acesteia pentru a primi un mesaj de utilizator gata de rulat.

Resurse

resources/list expune referințe publice, stocate în cache:

URI	Conținut
`thunderphone://docs/llms.txt`	Index public al documentației.
`thunderphone://docs/quickstart`	Markdown de pornire rapidă.
`thunderphone://pricing`	Markdown cu prețurile publice curente.

Citiți o resursă cu resources/read. Accesările publice folosesc un timp de expirare scurt, o limită de 2 MiB și un cache în proces de zece minute.

Protocol și erori

Serverul acceptă versiunile de protocol 2025-06-18 și 2025-03-26; returnează o versiune de client acceptată și, în caz contrar, selectează 2025-06-18. Implementează initialize, ping, instrumente, solicitări, resurse și notificări. Notificările returnează 202 Accepted. Acest server fără stare nu expune un listener SSE sau ștergerea sesiunilor, astfel încât GET și DELETE returnează 405 Method Not Allowed cu Allow: POST.

Eșecurile instrumentelor rămân răspunsuri JSON-RPC reușite cu isError: true. Textul lor conține o propoziție scurtă urmată de un bloc JSON:

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

Prefixul distinct outbound_tcpa_confirmation_required: este păstrat pentru place_call. Metodele JSON-RPC necunoscute returnează -32601 într-un răspuns HTTP 200. Loturile JSON-RPC nu sunt acceptate de MCP 2025-06-18 și returnează o eroare clară de solicitare nevalidă -32600.