---
title: "Gebruik ThunderPhone als een MCP-server"
description: "Bouw, test, valideer en beheer ThunderPhone-spraakagenten vanuit Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code of een andere Streamable HTTP MCP-client."
---

ThunderPhone stelt een Streamable HTTP-server voor het Model Context Protocol beschikbaar op:

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

Dit is de tegenovergestelde richting van [een externe MCP-server verbinden met een spraakagent](/nl/guides/mcp-servers):

| Richting | Resultaat |
| --- | --- |
| Externe MCP-server → ThunderPhone-agent | Een spraakagent kan de tools van de externe server aanroepen. |
| ThunderPhone → je MCP-client | Je programmeeragent kan ThunderPhone bouwen, testen en beheren. |

## Verifiëren

Gebruik standaard [OAuth](/nl/guides/oauth) voor directoryclients: log in, kies een organisatie en keur de gevraagde rechten goed. Trek toegang in via **Organisatie → API-sleutels → Geautoriseerde apps**.

Voor clients die met een API-sleutel zijn geconfigureerd, maak je een `sk_live_`-sleutel aan via **Organisatie → Sleutels** en stel je deze beschikbaar aan je MCP-client als `THUNDERPHONE_API_KEY`. De sleutel is gekoppeld aan één organisatie; een ID dat eigendom is van een andere organisatie gedraagt zich alsof het niet is gevonden.

<Warning>
  Een `sk_live_`-sleutel kan organisatiegegevens lezen en productieacties uitvoeren, zoals agents implementeren, oproepen plaatsen, nummers kopen, campagnes starten en resources verwijderen. Houd deze buiten browsercode, repositories, screenshots en chatlogboeken. Gebruik de geheime-opslag of omgevingsondersteuning van je client en trek een blootgestelde sleutel onmiddellijk in.
</Warning>

## CLI- en stdio-alternatieven

De [ThunderPhone CLI](/nl/guides/cli) kan clientconfiguratie schrijven met behoud van
niet-gerelateerde servers:

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

Na een globale installatie van `@thunderphone/mcp` gebruik je `thunderphone-mcp setup` met
dezelfde opties. Setup ondersteunt Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop en Windsurf. Directe HTTP heeft de voorkeur; Desktop gebruikt stdio.

Configureer voor elke client die stdio ondersteunt `command: "npx"` met
`args: ["-y", "@thunderphone/mcp"]`. De wrapper gebruikt eerst `THUNDERPHONE_API_KEY`,
daarna inloggegevens van `thunderphone login`, waarbij verlopen tokens worden vernieuwd, en vervolgens
OAuth via `mcp-remote`. Inloggen op apparaat en OAuth vereisen de bijbehorende API-
OAuth-uitrol. Het pad met API-sleutel niet. Directe HTTP-configuraties lezen
de CLI-opslag voor inloggegevens niet; gebruik de stdio-wrapper om inloggen op apparaat opnieuw te gebruiken.

Dit zijn alternatieven voor de handmatige clientconfiguraties hieronder.

## Clientconfiguratie

Claude en ChatGPT gebruiken [OAuth](/nl/guides/oauth) om in te loggen; er is geen API-sleutel nodig. Als je nog geen ThunderPhone-account hebt, kies je **Account maken** op de inlogpagina. Na het verifiëren van je e-mailadres keer je terug naar het goedkeuringsscherm.

### Claude (web, desktop en mobiel)

1. Open **Aanpassen → Connectors** (**Instellingen → Connectors** in oudere versies). Als ThunderPhone in de connectorlijst staat, selecteer je het. Kies anders **Aangepaste connector toevoegen**, geef deze de naam `ThunderPhone` en voer `https://api.thunderphone.com/v1/mcp` in.
2. Selecteer **Verbinden**, log in bij ThunderPhone, kies de organisatie en keur de machtigingen goed.
3. Schakel ThunderPhone in een chat in via het hulpmiddelenmenu en vraag wat je nodig hebt, bijvoorbeeld "Geef mijn agents weer".

Claude vraagt toestemming voordat het elke tool voor het eerst gebruikt. Om de meeste van die prompts over te slaan, open je **Aanpassen → Connectors → ThunderPhone** en stel je **Alleen-lezen-tools** in op altijd toestaan. Deze tools zoeken alleen informatie op: agents, oproepen, transcripties, tegoeden en documentatie. Laat **Schrijf-/verwijdertools** op goedkeuring staan als je elke wijziging wilt zien voordat deze wordt uitgevoerd.

Aangepaste connectors vereisen een betaald Claude-pakket. Bij Team- en Enterprise-pakketten voegt een eigenaar de connector eerst toe via de connectorinstellingen van de organisatie. Daarna koppelt elk lid zijn eigen ThunderPhone-account.

### ChatGPT

1. Als ThunderPhone in de ChatGPT-appdirectory staat, selecteer je het en maak je verbinding.
2. Open anders **Instellingen → Apps & Connectors → Geavanceerde instellingen**, schakel **Ontwikkelaarsmodus** in en maak een connector met de URL `https://api.thunderphone.com/v1/mcp` en OAuth-verificatie.
3. Log in bij ThunderPhone, kies de organisatie en keur de machtigingen goed. Voeg ThunderPhone via het hulpmiddelenmenu toe aan een chat.

Het verwijderen van een agent of telefoonnummer, het verwijderen van een concept, het starten van een campagne en het verzenden van een testverzoek dat naar een extern systeem kan schrijven, vereisen in beide apps een tweede bevestiging; zie [Destructieve acties bevestigen](#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

Voeg dit toe aan `~/.codex/config.toml`:

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

### Cursor

Maak `.cursor/mcp.json`:

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

### Claude Desktop

Voeg een `mcp-remote`-bridge toe aan de Claude Desktop-configuratie:

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

Maak `.vscode/mcp.json` en voer de sleutel in via de invoerprompt van 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}"
      }
    }
  }
}
```

## Hulpprogramma's

Elk hulpprogramma bevat MCP-annotaties. In de tabellen betekent **R** alleen-lezen, **D** destructief, **I** idempotent en **O** interactie met de open wereld/het netwerk. Een streepje betekent dat er geen hint is ingesteld.

### Verbinding

| Hulpprogramma | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Valideert de inloggegevens en retourneert de organisatie en veilige metagegevens van de inloggegevens. |

### Agenten

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Geeft agents weer. |
| `get_agent` | `agent_id` | R, I | Haalt één agent op. |
| `create_agent` | agentconfiguratie | — | Maakt een agent. |
| `update_agent` | `agent_id`, gewijzigde velden | D | Slaat velden op in het concept van de agent en vervangt wat er al in het concept stond. Wordt uitgevoerd zonder bevestigingsstap: de geïmplementeerde agent blijft ongewijzigd tot `deploy_agent`, en `discard_agent_draft` herstelt het concept. |
| `deploy_agent` | `agent_id`, optioneel `if_updated_at` | D, I | Zet het concept over naar productie. |
| `discard_agent_draft` | `agent_id`, optioneel `if_updated_at`, `confirmation_token` bij het tweede verzoek | D, I | Verwijdert opgeslagen wijzigingen. Twee stappen, zie [Destructieve acties bevestigen](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, optioneel `name` | — | Kopieert een agent binnen de organisatie. |
| `delete_agent` | `agent_id`, `confirmation_token` bij het tweede verzoek | D, I | Verwijdert een agent permanent. Twee stappen. |
| `list_agent_versions` | `agent_id` | R, I | Geeft geïmplementeerde configuratieversies weer. |

### Telefoonnummers en providers

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Geeft organisatienummers en routering weer. |
| `get_phone_number_limits` | — | R, I | Haalt gebruik en limieten van beheerde nummers op. |
| `provision_phone_number` | optioneel `area_code`, `city`, `state`, `idempotency_key` | D, O | Koopt een door ThunderPhone beheerd inkomend nummer. |
| `list_voip_connections` | — | R, I | Geeft verbonden providers van klanten weer. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, optioneel `area_code` | R, I, O | Doorzoekt de nummerinventaris van de provider. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importeert nummers die al eigendom zijn bij de provider. |
| `update_phone_number` | `phone_number_id`, velden voor routering/label/webhook | D | Werkt de routering van een nummer bij, inclusief toewijzing aan een agent. |
| `delete_phone_number` | `phone_number_id`, `confirm`, optioneel `release_at_provider`, `confirmation_token` bij het tweede verzoek | D, I, O | Geeft een nummer vrij. In twee stappen. |

### SMS

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Verstuurt één sms in platte tekst via een gekoppeld Twilio- of Telnyx-nummer. |

### Oproepen

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_calls` | optionele filters, `limit`, `offset` | R, I | Geeft oproepen weer met de REST-filters voor Oproepgeschiedenis. |
| `get_call` | `call_id` | R, I | Haalt de oproepstatus en metadata op. |
| `get_call_transcript` | `call_id`, optioneel `live` | R, I | Haalt het oproeptranscript op. |
| `get_call_audio_url` | `call_id`, optioneel `download` | R, I, O | Retourneert een ondertekende audio-URL; streamt audio nooit via MCP. |
| `get_call_grade` | `call_id` | R, I | Haalt de meest recente oproepbeoordeling op. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Plaatst één niet-idempotente uitgaande oproep. |
| `export_calls` | oproepfilters, `export_format` | R, I | Exporteert tot de limiet van het REST-eindpunt als JSON of CSV. |

### Testen en validatie

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Geeft een lijst met testscenario's. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, optionele voorwaarden | — | Maakt een scenario. |
| `generate_test_scenarios` | `agent_id`, optionele `count`, `include_edge_cases`, `locale` | O | Genereert scenario's op basis van de agentprompt. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, optionele selectie/matrix | D, O | Voert scenario's uit via het web of telefonie. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Haalt de batchstatus en resultaten per scenario op. |
| `list_validation_runs` | `agent_id` | R, I | Geeft een lijst met recente validatieruns voor concepten. |
| `get_validation_status` | `agent_id` | R, I | Haalt de nieuwste validatiestatus en overeenkomst met het concept op. |

### Kennis

| Hulpprogramma | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Geeft een lijst met kennisbanken. |
| `create_knowledge_base` | `name`, optioneel `description` | — | Maakt een kennisbank. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Voegt tekst of Markdown toe. |
| `import_knowledge_url` | `url`, optioneel `name` | O | Zet een openbare pagina in de wachtrij voor veilige opname. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Zoekt in productieretrieval. |

### Integraties, webhooks en externe MCP-servers

| Tool | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Geeft HTTP-functie-integraties weer. |
| `create_integration` | `display_name`, functie-`spec`, optionele eindpuntvelden | — | Maakt een HTTP-tool. Voeg verificatieheaders toe in het dashboard. |
| `test_integration` | `url`, optionele methode/body/time-out, `integration_id` met `header_names`, `confirmation_token` bij het tweede verzoek | D, O | Verstuurt een begrensd, tegen SSRF beveiligd testverzoek. Opgeslagen headerwaarden worden vanuit de integratie ingevuld en alleen naar de eigen host verzonden. `POST` (de standaardwaarde), `PUT`, `PATCH` en `DELETE` verlopen in twee stappen; `GET` wordt onmiddellijk uitgevoerd. |
| `list_webhook_endpoints` | — | R, I | Geeft ondertekende webhookeindpunten weer. |
| `list_webhook_deliveries` | optionele `agent_id`, optionele `endpoint_id` | R, I | Geeft recente resultaten van webhookleveringen zonder payload weer. |
| `create_webhook_endpoint` | `label`, `url`, optionele gebeurtenissen/status | O | Maakt een ondertekend webhookeindpunt. |
| `test_webhook_endpoint` | `endpoint_id` | O | Verstuurt een synthetische gebeurtenis via de normale levering. |
| `list_mcp_servers` | — | R, I | Geeft externe servers weer die door spraakagenten kunnen worden aangeroepen. |
| `create_mcp_server` | `display_name`, `url` | O | Registreert en synchroniseert een externe server. Servers waarvoor verificatieheaders nodig zijn, voeg je toe in het dashboard. |
| `sync_mcp_server_tools` | `server_id` | D, O | Vernieuwt de toolcatalogus van een externe server. |

### Campagnes

| Hulpprogramma | Belangrijkste argumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Geeft een lijst met uitgaande campagnes. |
| `create_campaign` | campagnevelden | — | Maakt een campagneconcept. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Voegt maximaal 5.000 JSON-contacten toe. |
| `campaign_action` | `campaign_id`, `action`, optioneel `consent_to_charge`, `confirmation_token` bij het tweede verzoek | D, O | Voert `start`, `pause`, `resume` of `stop` uit. `start` en `resume` verlopen in twee stappen; `pause` en `stop` worden onmiddellijk uitgevoerd. |
| `get_campaign_stats` | `campaign_id` | R, I | Haalt tellers en recente resultaten op. |

### Stemmen, facturering en documentatie

| Tool | Hoofdargumenten | Annotaties | Wat het doet |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Geeft stemmen en ondersteunde talen weer. |
| `preview_voice` | `voice`, `language`, `text` | O | Genereert een voorbeeld en retourneert een ondertekende URL. |
| `list_voice_clones` | — | R, I | Geeft aangepaste stemklonen weer. |
| `get_billing_summary` | — | R, I | Haalt het saldo en de officiële pakketprijzen op; er zijn geen betalingsmutaties beschikbaar. |
| `search_docs` | `query`, optionele `limit` | R, I, O | Doorzoekt de openbare documentatie-index. |
| `get_doc_page` | `path` | R, I, O | Haalt één openbare Markdown-documentatiepagina op. |

Alle producthulpprogramma's gebruiken dezelfde REST-codepaden als de openbare API. REST-validatie, organisatieafbakening, rollen, toelating voor facturering, quota's, TCPA-bevestiging, providerbeveiliging en auditgedrag zijn daarom ongewijzigd van toepassing.

## Destructieve acties bevestigen

Tools met de markering D wijzigen of verwijderen iets, of beginnen echte mensen te bellen. Voor acties die niet ongedaan kunnen worden gemaakt, zijn twee verzoeken nodig. Het eerste verzoek wijzigt niets en retourneert:

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

De assistent toont de gebruiker wat wordt beïnvloed en vraagt om een bevestiging. Vervolgens herhaalt deze het verzoek met dezelfde argumenten plus `confirmation_token`. Een token is 10 minuten geldig en geldt voor één organisatie, één tool en één exacte set argumenten, dus voor het verwijderen van drie agents zijn drie bevestigingen nodig. `campaign_action` met `pause` of `stop` slaat deze stap over, zodat een actieve campagne altijd direct kan worden gestopt. Hetzelfde geldt voor `test_integration` met `GET`. Sommige D-tools worden in één verzoek uitgevoerd omdat de D hun effect markeert, niet een bevestiging aan de serverzijde: `update_agent` vervangt wat het concept bevatte (`discard_agent_draft` draait dit terug), `deploy_agent` vervangt de actieve configuratie, `update_phone_number` leidt actieve oproepen om, `sync_mcp_server_tools` vervangt de toolcatalogus van een externe server, `import_voip_numbers` wijst nummers opnieuw toe aan je provider, `run_agent_tests` kan tegoed verbruiken, `send_sms` en `place_call` bereiken een echt persoon (`place_call` behoudt zijn eigen toestemmingsbevestiging) en `provision_phone_number` koopt een nummer. Je MCP-client kan je nog steeds vragen deze goed te keuren.

## Startprompts

`prompts/list` biedt vijf herbruikbare workflows:

- `create_inbound_receptionist`
- `run_agent_tests`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`

Gebruik `prompts/get` met de vermelde promptnaam en de opgegeven argumenten om een kant-en-klaar gebruikersbericht te ontvangen.

## Resources

`resources/list` biedt openbare, gecachte referenties:

| URI | Inhoud |
| --- | --- |
| `thunderphone://docs/llms.txt` | Openbare documentatie-index. |
| `thunderphone://docs/quickstart` | Quickstart-Markdown. |
| `thunderphone://pricing` | Actuele openbare prijsinformatie in Markdown. |

Lees er een met `resources/read`. Openbare ophaalverzoeken gebruiken een korte time-out, een limiet van 2 MiB en een procescache van tien minuten.

## Protocol en fouten

De server ondersteunt protocolversies `2025-06-18` en `2025-03-26`; deze echoot een ondersteunde clientversie en selecteert anders `2025-06-18`. De server implementeert `initialize`, `ping`, tools, prompts, resources en meldingen. Meldingen retourneren `202 Accepted`. Deze stateless server biedt geen SSE-listener of sessieverwijdering, dus `GET` en `DELETE` retourneren `405 Method Not Allowed` met `Allow: POST`.

Toolfouten blijven succesvolle JSON-RPC-antwoorden met `isError: true`. Hun tekst bevat een korte zin gevolgd door een JSON-blok:

```json
{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}
```

Het onderscheidende voorvoegsel `outbound_tcpa_confirmation_required:` blijft behouden voor `place_call`. Onbekende JSON-RPC-methoden retourneren `-32601` in een HTTP-antwoord met `200`. JSON-RPC-batches worden niet ondersteund door MCP `2025-06-18` en retourneren een duidelijke foutmelding `-32600` voor een ongeldig verzoek.