--- title: "Utilizați ThunderPhone ca server MCP" description: "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: ```text https://api.thunderphone.com/v1/mcp ``` Aceasta este direcția opusă față de [conectarea unui server MCP la distanță la un agent vocal](/ro/guides/mcp-servers): | 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](/ro/guides/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. O cheie `sk_live_` poate citi datele organizației și poate efectua acțiuni de producție, cum ar fi implementarea agenților, efectuarea apelurilor, cumpărarea numerelor, pornirea campaniilor și ștergerea resurselor. Nu o includeți în cod de browser, depozite, capturi de ecran și jurnale de chat. Utilizați stocarea de secrete sau suportul pentru mediu al clientului dumneavoastră și revocați imediat o cheie expusă. ## Alternative CLI și stdio [ThunderPhone CLI](/ro/guides/cli) poate scrie configurația clientului păstrând serverele fără legătură: ```bash 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](/ro/guides/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) 1. 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`. 2. Selectați **Conectare**, conectați-vă la ThunderPhone, alegeți organizația și aprobați permisiunile. 3. Î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 1. Dacă ThunderPhone apare în directorul de aplicații ChatGPT, selectați-l și conectați-vă. 2. Î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. 3. 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](#confirming-destructive-actions). ### Claude Code ```bash 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`: ```toml [mcp_servers.thunderphone] url = "https://api.thunderphone.com/v1/mcp" bearer_token_env_var = "THUNDERPHONE_API_KEY" ``` ### Cursor Creați `.cursor/mcp.json`: ```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: ```json { "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: ```json { "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](#confirming-destructive-actions). | | `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ă: ```json { "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: ```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`.