Utiliser ThunderPhone comme serveur MCP

Créez, testez, validez et exploitez des agents vocaux ThunderPhone depuis Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code ou un autre client MCP HTTP Streamable.

ThunderPhone met à disposition un serveur Model Context Protocol HTTP en streaming à l’adresse :

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

C’est l’inverse de la connexion d’un serveur MCP distant à un agent vocal :

Authentification#

Utilisez OAuth par défaut pour les clients de répertoire : connectez-vous, choisissez une organisation et approuvez les autorisations demandées. Révoquez l’accès dans Organisation → Clés API → Applications autorisées.

Pour les clients configurés avec une clé API, créez une clé sk_live_ dans Organisation → Clés et exposez-la à votre client MCP sous la forme THUNDERPHONE_API_KEY. La clé est associée à une seule organisation ; un identifiant appartenant à une autre organisation se comporte comme s’il était introuvable.

Alternatives CLI et stdio#

La CLI ThunderPhone peut écrire la configuration du client tout en préservant les serveurs non concernés :

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

Après une installation globale de @thunderphone/mcp, utilisez thunderphone-mcp setup avec les mêmes options. La configuration prend en charge Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop et Windsurf. HTTP direct est recommandé ; Desktop utilise stdio.

Pour tout client compatible stdio, configurez command: "npx" avec args: ["-y", "@thunderphone/mcp"]. Le wrapper utilise d’abord THUNDERPHONE_API_KEY, puis les identifiants de thunderphone login, en actualisant les jetons expirés, puis OAuth via mcp-remote. La connexion par appareil et OAuth nécessitent le déploiement OAuth correspondant de l’API. Le parcours avec clé API ne le nécessite pas. Les configurations HTTP direct ne lisent pas le stockage d’identifiants de la CLI ; utilisez le wrapper stdio pour réutiliser la connexion par appareil.

Il s’agit d’alternatives aux configurations manuelles des clients ci-dessous.

Configuration du client#

Claude et ChatGPT utilisent OAuth pour se connecter ; aucune clé API n’est nécessaire. Si vous n’avez pas encore de compte ThunderPhone, choisissez Créer un compte sur la page de connexion ; après avoir vérifié votre e-mail, vous revenez à l’écran d’autorisation.

Claude (web, ordinateur et mobile)#

1. Ouvrez Personnaliser → Connecteurs (Paramètres → Connecteurs dans les versions antérieures). Si ThunderPhone apparaît dans le répertoire des connecteurs, sélectionnez-le. Sinon, choisissez Ajouter un connecteur personnalisé, nommez-le ThunderPhone et saisissez https://api.thunderphone.com/v1/mcp.
2. Sélectionnez Connecter, connectez-vous à ThunderPhone, choisissez l’organisation et approuvez les autorisations.
3. Dans une conversation, activez ThunderPhone depuis le menu des outils et demandez ce dont vous avez besoin, par exemple « Répertorie mes agents ».

Claude vous demande une autorisation avant d’utiliser chaque outil pour la première fois. Pour ignorer la plupart de ces invites, ouvrez Personnaliser → Connecteurs → ThunderPhone et définissez Outils en lecture seule sur toujours autoriser. Ces outils effectuent uniquement des recherches : agents, appels, transcriptions, soldes, Docs. Laissez Outils d’écriture/suppression en mode approbation si vous souhaitez voir chaque modification avant qu’elle ne soit appliquée.

Les connecteurs personnalisés nécessitent un forfait Claude payant. Avec les forfaits Team et Enterprise, un propriétaire ajoute d’abord le connecteur dans les paramètres des connecteurs de l’organisation, puis chaque membre connecte son propre compte ThunderPhone.

ChatGPT#

1. Si ThunderPhone apparaît dans le répertoire d’applications de ChatGPT, sélectionnez-le et connectez-le.
2. Sinon, ouvrez Paramètres → Applications et connecteurs → Paramètres avancés, activez le Mode développeur, puis créez un connecteur avec l’URL https://api.thunderphone.com/v1/mcp et l’authentification OAuth.
3. Connectez-vous à ThunderPhone, choisissez l’organisation et approuvez les autorisations. Ajoutez ThunderPhone à une conversation depuis le menu des outils.

La suppression d’un agent ou d’un numéro de téléphone, l’abandon d’un brouillon, le lancement d’une campagne et l’envoi d’une requête de test pouvant écrire dans un système externe nécessitent une seconde confirmation dans les deux applications ; consultez Confirmation des actions destructrices.

Claude Code#

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

Codex#

Ajoutez ceci à ~/.codex/config.toml :

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

Cursor#

Créez .cursor/mcp.json :

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

Claude Desktop#

Ajoutez un pont mcp-remote à la configuration de 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#

Créez .vscode/mcp.json et saisissez la clé via l’invite de saisie de 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}"
      }
    }
  }
}

Outils#

Chaque outil comporte des annotations MCP. Dans les tableaux, R signifie lecture seule, D destructif, I idempotent et O interaction avec le monde extérieur/le réseau. Un tiret indique qu'aucun indice n'est défini.

Connexion#

Agents#

Numéros de téléphone et opérateurs#

SMS#

Appels#

Tests et validation#

Connaissances#

Intégrations, webhooks et serveurs MCP distants#

Campagnes#

Voix, facturation et documentation#

Tous les outils produit utilisent les mêmes chemins de code REST que l'API publique. La validation REST, le périmètre de l'organisation, les rôles, l'admission de facturation, les quotas, la confirmation TCPA, la sécurité des fournisseurs et le comportement d'audit s'appliquent donc sans modification.

Confirmation des actions destructrices#

Les outils marqués D modifient ou suppriment quelque chose, ou commencent à appeler de vraies personnes. Ceux qui ne peuvent pas être annulés nécessitent deux requêtes. La première requête ne modifie rien et renvoie :

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

L’assistant indique à l’utilisateur ce qui est concerné et lui demande de confirmer. Il répète ensuite la requête avec les mêmes arguments, auxquels s’ajoute confirmation_token. Un jeton est valide pendant 10 minutes et couvre une organisation, un outil et un ensemble exact d’arguments. La suppression de trois agents nécessite donc trois confirmations. campaign_action avec pause ou stop ignore cette étape afin qu’une campagne en cours puisse toujours être arrêtée immédiatement, tout comme test_integration avec GET. Certains outils D s’exécutent en une requête, car le D indique leur effet et non une confirmation côté serveur : update_agent remplace le contenu du brouillon (discard_agent_draft l’annule), deploy_agent remplace la configuration active, update_phone_number modifie le routage des appels en direct, sync_mcp_server_tools remplace le catalogue d’outils d’un serveur distant, import_voip_numbers redirige les numéros vers votre opérateur, run_agent_tests peut consommer du crédit, send_sms et place_call contactent une vraie personne (place_call conserve sa propre confirmation de consentement), et provision_phone_number achète un numéro. Votre client MCP peut toujours vous demander de les approuver.

Prompts de démarrage#

prompts/list propose cinq workflows réutilisables :

• create_inbound_receptionist
• run_agent_tests
• buy_and_attach_number
• review_low_grade_calls
• add_url_to_agent_knowledge

Utilisez prompts/get avec le nom du prompt indiqué et ses arguments déclarés pour recevoir un message utilisateur prêt à exécuter.

Ressources#

resources/list expose des références publiques mises en cache :

Lisez-en une avec resources/read. Les récupérations publiques utilisent un court délai d’expiration, une limite de 2 MiB et un cache en processus de dix minutes.

Protocole et erreurs#

Le serveur prend en charge les versions de protocole 2025-06-18 et 2025-03-26 ; il renvoie en écho une version client prise en charge et sélectionne sinon 2025-06-18. Il implémente initialize, ping, les outils, les prompts, les ressources et les notifications. Les notifications renvoient 202 Accepted. Ce serveur sans état n’expose pas d’écouteur SSE ni de suppression de session ; GET et DELETE renvoient donc 405 Method Not Allowed avec Allow: POST.

Les échecs d’outils restent des réponses JSON-RPC réussies avec isError: true. Leur texte contient une courte phrase suivie d’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."
}

Le préfixe distinct outbound_tcpa_confirmation_required: est conservé pour place_call. Les méthodes JSON-RPC inconnues renvoient -32601 dans une réponse HTTP 200. Les lots JSON-RPC ne sont pas pris en charge par MCP 2025-06-18 et renvoient une erreur de requête non valide -32600 claire.