---
title: "Utiliser ThunderPhone comme serveur MCP"
description: "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 :

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

C’est l’inverse de la [connexion d’un serveur MCP distant à un agent vocal](/fr/guides/mcp-servers) :

| Direction | Résultat |
| --- | --- |
| Serveur MCP distant → agent ThunderPhone | Un agent vocal peut appeler les outils du serveur distant. |
| ThunderPhone → votre client MCP | Votre agent de programmation peut créer, tester et exploiter ThunderPhone. |

## Authentification

Utilisez [OAuth](/fr/guides/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.

<Warning>
  Une clé `sk_live_` peut lire les données de l’organisation et effectuer des actions de production telles que déployer des agents, passer des appels, acheter des numéros, lancer des campagnes et supprimer des ressources. Ne l’incluez pas dans du code navigateur, des dépôts, des captures d’écran ou des journaux de discussion. Utilisez le stockage de secrets ou la prise en charge des variables d’environnement de votre client, et révoquez immédiatement toute clé exposée.
</Warning>

## Alternatives CLI et stdio

La [CLI ThunderPhone](/fr/guides/cli) peut écrire la configuration du client tout en préservant
les serveurs non concernés :

```bash
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](/fr/guides/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](#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

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

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

### Cursor

Créez `.cursor/mcp.json` :

```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 :

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

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

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

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Valide l'identifiant et renvoie son organisation ainsi que les métadonnées sûres de l'identifiant. |

### Agents

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Liste les agents. |
| `get_agent` | `agent_id` | R, I | Récupère un agent. |
| `create_agent` | configuration de l’agent | — | Crée un agent. |
| `update_agent` | `agent_id`, champs modifiés | D | Prépare les champs dans le brouillon de l’agent, en remplaçant ceux déjà présents dans le brouillon. S’exécute sans étape de confirmation : l’agent déployé reste inchangé jusqu’à `deploy_agent`, et `discard_agent_draft` rétablit le brouillon. |
| `deploy_agent` | `agent_id`, `if_updated_at` facultatif | D, I | Promeut le brouillon en production. |
| `discard_agent_draft` | `agent_id`, `if_updated_at` facultatif, `confirmation_token` lors de la deuxième requête | D, I | Abandonne les modifications préparées. En deux étapes, voir [Confirmation des actions destructrices](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, `name` facultatif | — | Copie un agent au sein de l’organisation. |
| `delete_agent` | `agent_id`, `confirmation_token` lors de la deuxième requête | D, I | Supprime définitivement un agent. En deux étapes. |
| `list_agent_versions` | `agent_id` | R, I | Liste les versions de configuration déployées. |

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

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Répertorie les numéros de l’organisation et leur routage. |
| `get_phone_number_limits` | — | R, I | Récupère l’utilisation et les limites des numéros gérés. |
| `provision_phone_number` | `area_code`, `city`, `state`, `idempotency_key` facultatifs | D, O | Achète un numéro entrant géré par ThunderPhone. |
| `list_voip_connections` | — | R, I | Répertorie les opérateurs du client connectés. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, `area_code` facultatif | R, I, O | Recherche dans l’inventaire de l’opérateur. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importe des numéros déjà détenus chez l’opérateur. |
| `update_phone_number` | `phone_number_id`, champs de routage/libellé/webhook | D | Met à jour le routage du numéro, y compris l’affectation à un agent. |
| `delete_phone_number` | `phone_number_id`, `confirm`, `release_at_provider` facultatif, `confirmation_token` lors de la deuxième requête | D, I, O | Libère un numéro. En deux étapes. |

### SMS

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Envoie un SMS en texte brut via un numéro Twilio ou Telnyx connecté. |

### Appels

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_calls` | filtres facultatifs, `limit`, `offset` | R, I | Répertorie les appels avec les filtres d'historique des appels REST. |
| `get_call` | `call_id` | R, I | Récupère le statut et les métadonnées de l'appel. |
| `get_call_transcript` | `call_id`, `live` facultatif | R, I | Récupère la transcription de l'appel. |
| `get_call_audio_url` | `call_id`, `download` facultatif | R, I, O | Renvoie une URL audio signée ; ne diffuse jamais l'audio via MCP. |
| `get_call_grade` | `call_id` | R, I | Récupère la dernière évaluation de l'appel. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Passe un appel sortant non idempotent. |
| `export_calls` | filtres d'appel, `export_format` | R, I | Exporte jusqu'à la limite du point de terminaison REST au format JSON ou CSV. |

### Tests et validation

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Liste les scénarios de test. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, conditions facultatives | — | Crée un scénario. |
| `generate_test_scenarios` | `agent_id`, `count` facultatif, `include_edge_cases`, `locale` | O | Génère des scénarios à partir du prompt de l'agent. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, sélection/matrice facultative | D, O | Exécute des scénarios via le web ou la téléphonie. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Obtient le statut du lot et les résultats par scénario. |
| `list_validation_runs` | `agent_id` | R, I | Liste les récentes exécutions de validation des brouillons. |
| `get_validation_status` | `agent_id` | R, I | Obtient le dernier état de validation et la correspondance avec le brouillon. |

### Connaissances

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Répertorie les bases de connaissances. |
| `create_knowledge_base` | `name`, `description` facultative | — | Crée une base de connaissances. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Ajoute du texte ou du Markdown. |
| `import_knowledge_url` | `url`, `name` facultatif | O | Met une page publique en file d'attente pour une ingestion sûre. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Recherche dans le système de récupération en production. |

### Intégrations, webhooks et serveurs MCP distants

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Répertorie les intégrations de fonctions HTTP. |
| `create_integration` | `display_name`, `spec` de fonction, champs de point de terminaison facultatifs | — | Crée un outil HTTP. Ajoutez les en-têtes d’authentification dans le tableau de bord. |
| `test_integration` | `url`, méthode/corps/délai d’expiration facultatifs, `integration_id` avec `header_names`, `confirmation_token` lors de la deuxième requête | D, O | Envoie une requête de test limitée et protégée contre les SSRF. Les valeurs d’en-tête enregistrées sont renseignées depuis l’intégration et envoyées uniquement à son propre hôte. `POST` (par défaut), `PUT`, `PATCH` et `DELETE` se déroulent en deux étapes ; `GET` s’exécute immédiatement. |
| `list_webhook_endpoints` | — | R, I | Répertorie les points de terminaison de webhook signés. |
| `list_webhook_deliveries` | `agent_id` facultatif, `endpoint_id` facultatif | R, I | Répertorie les résultats récents de livraison de webhooks sans charge utile. |
| `create_webhook_endpoint` | `label`, `url`, événements/statut facultatifs | O | Crée un point de terminaison de webhook signé. |
| `test_webhook_endpoint` | `endpoint_id` | O | Envoie un événement synthétique via la livraison normale. |
| `list_mcp_servers` | — | R, I | Répertorie les serveurs distants appelables par les agents vocaux. |
| `create_mcp_server` | `display_name`, `url` | O | Enregistre et synchronise un serveur distant. Les serveurs nécessitant des en-têtes d’authentification sont ajoutés dans le tableau de bord. |
| `sync_mcp_server_tools` | `server_id` | D, O | Actualise le catalogue d’outils d’un serveur distant. |

### Campagnes

| Outil | Arguments principaux | Annotations | Fonction |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Répertorie les campagnes sortantes. |
| `create_campaign` | champs de campagne | — | Crée une campagne brouillon. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Ajoute jusqu'à 5 000 contacts JSON. |
| `campaign_action` | `campaign_id`, `action`, `consent_to_charge` facultatif, `confirmation_token` lors de la deuxième requête | D, O | Exécute `start`, `pause`, `resume` ou `stop`. `start` et `resume` s'effectuent en deux étapes ; `pause` et `stop` s'exécutent immédiatement. |
| `get_campaign_stats` | `campaign_id` | R, I | Récupère les compteurs et les résultats récents. |

### Voix, facturation et documentation

| Outil | Arguments principaux | Annotations | Ce qu’il fait |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Liste les voix et les langues prises en charge. |
| `preview_voice` | `voice`, `language`, `text` | O | Génère un échantillon et renvoie une URL signée. |
| `list_voice_clones` | — | R, I | Liste les clones vocaux personnalisés. |
| `get_billing_summary` | — | R, I | Obtient le solde et les prix officiels des niveaux ; aucune modification de paiement n’est exposée. |
| `search_docs` | `query`, `limit` facultatif | R, I, O | Recherche dans l’index de la documentation publique. |
| `get_doc_page` | `path` | R, I, O | Récupère une page de documentation publique au format Markdown. |

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 :

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

| URI | Contenu |
| --- | --- |
| `thunderphone://docs/llms.txt` | Index de la documentation publique. |
| `thunderphone://docs/quickstart` | Markdown de démarrage rapide. |
| `thunderphone://pricing` | Markdown des tarifs publics actuels. |

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 :

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