Usa ThunderPhone come server MCP

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:

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

Questa è la direzione opposta rispetto a collegare un server MCP remoto a un voice agent:

Autenticazione#

Per impostazione predefinita, usa 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.

Alternative CLI e stdio#

La CLI di ThunderPhone può scrivere la configurazione del client mantenendo i server non correlati:

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 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.

Claude Code#

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:

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

Cursor#

Crea .cursor/mcp.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:

{
  "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:

{
  "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#

Agenti#

Numeri di telefono e operatori#

SMS#

Chiamate#

Test e convalida#

Knowledge#

Integrazioni, webhook e server MCP remoti#

Campagne#

Voci, fatturazione e documentazione#

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:

{
  "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:

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:

{
  "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.