--- title: "Usa ThunderPhone come server MCP" description: "Crea, testa, convalida e gestisci gli agenti vocali ThunderPhone da Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code o un altro client MCP Streamable HTTP." --- ThunderPhone espone un server Model Context Protocol HTTP streaming all'indirizzo: ```text https://api.thunderphone.com/v1/mcp ``` Questa è la direzione opposta rispetto a [collegare un server MCP remoto a un voice agent](/it/guides/mcp-servers): | Direzione | Risultato | | --- | --- | | Server MCP remoto → agente ThunderPhone | Un voice agent può chiamare gli strumenti del server remoto. | | ThunderPhone → il tuo client MCP | Il tuo agente di coding può creare, testare e gestire ThunderPhone. | ## Autenticazione Per impostazione predefinita, usa [OAuth](/it/guides/oauth) per i client della directory: accedi, scegli un'organizzazione e approva le autorizzazioni richieste. Revoca l'accesso in **Organizzazione → Chiavi API → App autorizzate**. Per i client configurati con una chiave API, crea una chiave `sk_live_` in **Organizzazione → Chiavi** ed esponila al tuo client MCP come `THUNDERPHONE_API_KEY`. La chiave è associata a una sola organizzazione; un ID appartenente a un'altra organizzazione si comporta come se non fosse stato trovato. Una chiave `sk_live_` può leggere i dati dell'organizzazione ed eseguire azioni in produzione come distribuire agenti, effettuare chiamate, acquistare numeri, avviare campagne ed eliminare risorse. Non inserirla nel codice del browser, nei repository, negli screenshot e nei log delle chat. Usa l'archivio dei segreti o il supporto per le variabili d'ambiente del tuo client e revoca immediatamente una chiave esposta. ## Alternative CLI e stdio La [CLI di ThunderPhone](/it/guides/cli) può scrivere la configurazione del client mantenendo i server non correlati: ```bash npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY npx thunderphone mcp setup --client claude-desktop --scope user ``` Dopo un'installazione globale di `@thunderphone/mcp`, usa `thunderphone-mcp setup` con le stesse opzioni. La configurazione supporta Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop e Windsurf. È preferibile HTTP diretto; Desktop usa stdio. Per qualsiasi client compatibile con stdio, configura `command: "npx"` con `args: ["-y", "@thunderphone/mcp"]`. Il wrapper usa prima `THUNDERPHONE_API_KEY`, poi le credenziali di `thunderphone login`, aggiornando i token scaduti, quindi OAuth tramite `mcp-remote`. L'accesso da dispositivo e OAuth richiedono il corrispondente rilascio OAuth dell'API. Il percorso con chiave API no. Le configurazioni HTTP dirette non leggono l'archivio credenziali della CLI; usa il wrapper stdio per riutilizzare l'accesso da dispositivo. Queste sono alternative alle configurazioni manuali del client riportate di seguito. ## Configurazione del client Claude e ChatGPT usano [OAuth](/it/guides/oauth) per l'accesso; non è coinvolta alcuna chiave API. Se non hai ancora un account ThunderPhone, scegli **Crea account** nella pagina di accesso e, dopo aver verificato la tua email, tornerai alla schermata di approvazione. ### Claude (web, desktop e mobile) 1. Apri **Personalizza → Connettori** (**Impostazioni → Connettori** nelle versioni precedenti). Se ThunderPhone appare nella directory dei connettori, selezionalo. Altrimenti scegli **Aggiungi connettore personalizzato**, assegnagli il nome `ThunderPhone` e inserisci `https://api.thunderphone.com/v1/mcp`. 2. Seleziona **Connetti**, accedi a ThunderPhone, scegli l'organizzazione e approva le autorizzazioni. 3. In una chat, abilita ThunderPhone dal menu degli strumenti e chiedi ciò di cui hai bisogno, ad esempio "Elenca i miei agenti". Claude chiede conferma prima di usare ogni strumento per la prima volta. Per saltare la maggior parte di queste richieste, apri **Personalizza → Connettori → ThunderPhone** e imposta **Strumenti di sola lettura** su sempre consentiti. Questi strumenti eseguono solo ricerche: agenti, chiamate, trascrizioni, saldi, documenti. Lascia **Strumenti di scrittura/eliminazione** con approvazione se vuoi vedere ogni modifica prima che avvenga. I connettori personalizzati richiedono un piano Claude a pagamento. Nei piani Team ed Enterprise, un proprietario aggiunge prima il connettore nelle impostazioni dei connettori dell'organizzazione, poi ogni membro collega il proprio account ThunderPhone. ### ChatGPT 1. Se ThunderPhone appare nella directory delle app di ChatGPT, selezionalo e connettilo. 2. Altrimenti apri **Impostazioni → App e connettori → Impostazioni avanzate**, attiva **Modalità sviluppatore** e crea un connettore con l'URL `https://api.thunderphone.com/v1/mcp` e autenticazione OAuth. 3. Accedi a ThunderPhone, scegli l'organizzazione e approva le autorizzazioni. Aggiungi ThunderPhone a una chat dal menu degli strumenti. L'eliminazione di un agente o di un numero di telefono, l'eliminazione di una bozza, l'avvio di una campagna e l'invio di una richiesta di test che può scrivere in un sistema esterno richiedono una seconda conferma in entrambe le app; vedi [Conferma delle azioni distruttive](#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 Aggiungi questo a `~/.codex/config.toml`: ```toml [mcp_servers.thunderphone] url = "https://api.thunderphone.com/v1/mcp" bearer_token_env_var = "THUNDERPHONE_API_KEY" ``` ### Cursor Crea `.cursor/mcp.json`: ```json { "mcpServers": { "thunderphone": { "url": "https://api.thunderphone.com/v1/mcp", "headers": { "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}" } } } } ``` ### Claude Desktop Aggiungi un bridge `mcp-remote` alla configurazione di 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 `.vscode/mcp.json` e inserisci la chiave tramite la richiesta di input di 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}" } } } } ``` ## Strumenti Ogni strumento include annotazioni MCP. Nelle tabelle, **R** indica sola lettura, **D** distruttivo, **I** idempotente e **O** interazione con rete/mondo esterno. Un trattino indica che non è impostato alcun suggerimento. ### Connessione | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `get_connection_identity` | — | R, I | Convalida le credenziali e restituisce la relativa organizzazione e metadati sicuri delle credenziali. | ### Agenti | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_agents` | — | R, I | Elenca gli agenti. | | `get_agent` | `agent_id` | R, I | Recupera un agente. | | `create_agent` | configurazione dell'agente | — | Crea un agente. | | `update_agent` | `agent_id`, campi modificati | D | Prepara i campi nella bozza dell'agente, sostituendo quelli presenti nella bozza. Viene eseguito senza un passaggio di conferma: l'agente distribuito resta invariato fino a `deploy_agent`, mentre `discard_agent_draft` ripristina la bozza. | | `deploy_agent` | `agent_id`, `if_updated_at` facoltativo | D, I | Promuove la bozza in produzione. | | `discard_agent_draft` | `agent_id`, `if_updated_at` facoltativo, `confirmation_token` nella seconda richiesta | D, I | Elimina le modifiche preparate. Procedura in due passaggi; vedi [Conferma delle azioni distruttive](#confirming-destructive-actions). | | `duplicate_agent` | `agent_id`, `name` facoltativo | — | Copia un agente all'interno dell'organizzazione. | | `delete_agent` | `agent_id`, `confirmation_token` nella seconda richiesta | D, I | Elimina definitivamente un agente. Procedura in due passaggi. | | `list_agent_versions` | `agent_id` | R, I | Elenca le versioni di configurazione distribuite. | ### Numeri di telefono e operatori | Strumento | Argomenti principali | Annotazioni | Funzione | | --- | --- | --- | --- | | `list_phone_numbers` | — | R, I | Elenca i numeri dell'organizzazione e il routing. | | `get_phone_number_limits` | — | R, I | Ottiene l'utilizzo e i limiti dei numeri gestiti. | | `provision_phone_number` | facoltativi `area_code`, `city`, `state`, `idempotency_key` | D, O | Acquista un numero in entrata gestito da ThunderPhone. | | `list_voip_connections` | — | R, I | Elenca gli operatori del cliente connessi. | | `search_voip_numbers` | `connection_id`, `country`, `type`, facoltativo `area_code` | R, I, O | Cerca nell'inventario dell'operatore. | | `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importa numeri già posseduti presso l'operatore. | | `update_phone_number` | `phone_number_id`, campi di routing/etichetta/webhook | D | Aggiorna il routing del numero, inclusa l'assegnazione dell'agente. | | `delete_phone_number` | `phone_number_id`, `confirm`, facoltativo `release_at_provider`, `confirmation_token` nella seconda richiesta | D, I, O | Rilascia un numero. In due passaggi. | ### SMS | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Invia un SMS in testo semplice tramite un numero Twilio o Telnyx connesso. | ### Chiamate | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_calls` | filtri facoltativi, `limit`, `offset` | R, I | Elenca le chiamate con i filtri REST della cronologia chiamate. | | `get_call` | `call_id` | R, I | Ottiene lo stato e i metadati della chiamata. | | `get_call_transcript` | `call_id`, `live` facoltativo | R, I | Ottiene la trascrizione della chiamata. | | `get_call_audio_url` | `call_id`, `download` facoltativo | R, I, O | Restituisce un URL audio firmato; non trasmette mai l'audio tramite MCP. | | `get_call_grade` | `call_id` | R, I | Ottiene l'ultima valutazione della chiamata. | | `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Effettua una chiamata in uscita non idempotente. | | `export_calls` | filtri chiamate, `export_format` | R, I | Esporta fino al limite dell'endpoint REST in formato JSON o CSV. | ### Test e convalida | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_test_scenarios` | `agent_id` | R, I | Elenca gli scenari di test. | | `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, condizioni facoltative | — | Crea uno scenario. | | `generate_test_scenarios` | `agent_id`, `count` facoltativo, `include_edge_cases`, `locale` | O | Genera scenari dal prompt dell'agente. | | `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, selezione/matrice facoltativa | D, O | Esegue gli scenari tramite web o telefonia. | | `get_test_run` | `agent_id`, `batch_id` | R, I | Ottiene lo stato del batch e i risultati per scenario. | | `list_validation_runs` | `agent_id` | R, I | Elenca le esecuzioni di convalida recenti della bozza. | | `get_validation_status` | `agent_id` | R, I | Ottiene lo stato di convalida più recente e la corrispondenza della bozza. | ### Knowledge | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_knowledge_bases` | — | R, I | Elenca le basi di conoscenza. | | `create_knowledge_base` | `name`, `description` facoltativo | — | Crea una base di conoscenza. | | `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Aggiunge testo o Markdown. | | `import_knowledge_url` | `url`, `name` facoltativo | O | Mette in coda una pagina pubblica per l'importazione sicura. | | `search_knowledge` | `knowledge_base_id`, `query` | R, I | Cerca nel recupero dati di produzione. | ### Integrazioni, webhook e server MCP remoti | Strumento | Argomenti principali | Annotazioni | Funzione | | --- | --- | --- | --- | | `list_integrations` | — | R, I | Elenca le integrazioni di funzioni HTTP. | | `create_integration` | `display_name`, `spec` della funzione, campi endpoint facoltativi | — | Crea uno strumento HTTP. Aggiungi le intestazioni di autenticazione nel dashboard. | | `test_integration` | `url`, metodo/corpo/timeout facoltativi, `integration_id` con `header_names`, `confirmation_token` nella seconda richiesta | D, O | Invia una richiesta di test limitata e protetta da SSRF. I valori delle intestazioni salvati vengono compilati dall'integrazione e inviati solo al relativo host. `POST` (predefinito), `PUT`, `PATCH` e `DELETE` prevedono due passaggi; `GET` viene eseguito immediatamente. | | `list_webhook_endpoints` | — | R, I | Elenca gli endpoint webhook firmati. | | `list_webhook_deliveries` | `agent_id` facoltativo, `endpoint_id` facoltativo | R, I | Elenca gli esiti recenti delle consegne webhook senza payload. | | `create_webhook_endpoint` | `label`, `url`, eventi/stato facoltativi | O | Crea un endpoint webhook firmato. | | `test_webhook_endpoint` | `endpoint_id` | O | Invia un evento sintetico tramite la normale consegna. | | `list_mcp_servers` | — | R, I | Elenca i server remoti richiamabili dagli agenti vocali. | | `create_mcp_server` | `display_name`, `url` | O | Registra e sincronizza un server remoto. I server che richiedono intestazioni di autenticazione vengono aggiunti nel dashboard. | | `sync_mcp_server_tools` | `server_id` | D, O | Aggiorna il catalogo degli strumenti di un server remoto. | ### Campagne | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_campaigns` | — | R, I | Elenca le campagne in uscita. | | `create_campaign` | campi della campagna | — | Crea una bozza di campagna. | | `add_campaign_contacts` | `campaign_id`, `contacts` | — | Aggiunge fino a 5.000 contatti JSON. | | `campaign_action` | `campaign_id`, `action`, `consent_to_charge` facoltativo, `confirmation_token` nella seconda richiesta | D, O | Esegue `start`, `pause`, `resume` o `stop`. `start` e `resume` richiedono due passaggi; `pause` e `stop` vengono eseguiti immediatamente. | | `get_campaign_stats` | `campaign_id` | R, I | Ottiene contatori ed esiti recenti. | ### Voci, fatturazione e documentazione | Strumento | Argomenti principali | Annotazioni | Cosa fa | | --- | --- | --- | --- | | `list_voices` | — | R, I | Elenca le voci e le lingue supportate. | | `preview_voice` | `voice`, `language`, `text` | O | Genera un campione e restituisce un URL firmato. | | `list_voice_clones` | — | R, I | Elenca i cloni vocali personalizzati. | | `get_billing_summary` | — | R, I | Recupera il saldo e i prezzi autorevoli dei livelli; non espone modifiche ai pagamenti. | | `search_docs` | `query`, optional `limit` | R, I, O | Cerca nell'indice pubblico della documentazione. | | `get_doc_page` | `path` | R, I, O | Recupera una pagina pubblica della documentazione in Markdown. | Tutti gli strumenti di prodotto utilizzano gli stessi percorsi di codice REST dell'API pubblica. La convalida REST, l'ambito dell'organizzazione, i ruoli, l'ammissione alla fatturazione, le quote, la conferma TCPA, la sicurezza del provider e il comportamento di audit si applicano quindi senza modifiche. ## Conferma delle azioni distruttive Gli strumenti contrassegnati con D modificano o rimuovono qualcosa, oppure iniziano a chiamare persone reali. Quelli che non possono essere annullati richiedono due richieste. La prima richiesta non modifica nulla e restituisce: ```json { "status": "confirmation_required", "action": "Delete agent", "target": { "id": 195, "name": "Front Desk Receptionist" }, "confirmation_token": "…", "expires_in_seconds": 600, "next_step": "…" } ``` L'assistente mostra all'utente cosa viene interessato e chiede una conferma. Quindi ripete la richiesta con gli stessi argomenti più `confirmation_token`. Un token è valido per 10 minuti e copre un'organizzazione, uno strumento e un insieme esatto di argomenti, quindi l'eliminazione di tre agenti richiede tre conferme. `campaign_action` con `pause` o `stop` salta questo passaggio, in modo che una campagna in esecuzione possa sempre essere interrotta subito; lo stesso vale per `test_integration` con `GET`. Alcuni strumenti D vengono eseguiti in una richiesta perché la D indica il loro effetto, non una conferma lato server: `update_agent` sostituisce il contenuto della bozza (`discard_agent_draft` lo ripristina), `deploy_agent` sostituisce la configurazione attiva, `update_phone_number` reindirizza le chiamate attive, `sync_mcp_server_tools` sostituisce il catalogo degli strumenti di un server remoto, `import_voip_numbers` reindirizza i numeri al tuo operatore, `run_agent_tests` può consumare credito, `send_sms` e `place_call` contattano una persona reale (`place_call` mantiene la propria conferma di consenso) e `provision_phone_number` acquista un numero. Il tuo client MCP potrebbe comunque chiederti di approvarli. ## Prompt iniziali `prompts/list` presenta cinque flussi di lavoro riutilizzabili: - `create_inbound_receptionist` - `run_agent_tests` - `buy_and_attach_number` - `review_low_grade_calls` - `add_url_to_agent_knowledge` Usa `prompts/get` con il nome del prompt elencato e i relativi argomenti dichiarati per ricevere un messaggio utente pronto all'esecuzione. ## Risorse `resources/list` espone riferimenti pubblici memorizzati nella cache: | URI | Contenuto | | --- | --- | | `thunderphone://docs/llms.txt` | Indice della documentazione pubblica. | | `thunderphone://docs/quickstart` | Markdown della guida rapida. | | `thunderphone://pricing` | Markdown dei prezzi pubblici correnti. | Leggine una con `resources/read`. I recuperi pubblici utilizzano un timeout breve, un limite di 2 MiB e una cache in-process di dieci minuti. ## Protocollo ed errori Il server supporta le versioni del protocollo `2025-06-18` e `2025-03-26`; ripete una versione client supportata e altrimenti seleziona `2025-06-18`. Implementa `initialize`, `ping`, strumenti, prompt, risorse e notifiche. Le notifiche restituiscono `202 Accepted`. Questo server senza stato non espone un listener SSE né l'eliminazione di sessioni, pertanto `GET` e `DELETE` restituiscono `405 Method Not Allowed` con `Allow: POST`. Gli errori degli strumenti restano risposte JSON-RPC riuscite con `isError: true`. Il relativo testo contiene una frase breve seguita da un blocco 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." } ``` Il prefisso distinto `outbound_tcpa_confirmation_required:` viene mantenuto per `place_call`. I metodi JSON-RPC sconosciuti restituiscono `-32601` in una risposta HTTP `200`. I batch JSON-RPC non sono supportati da MCP `2025-06-18` e restituiscono un errore di richiesta non valida `-32600` pulito.