Open in

Gebruik ThunderPhone als een MCP-server

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:

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

Dit is de tegenovergestelde richting van een externe MCP-server verbinden met een spraakagent:

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

CLI- en stdio-alternatieven

De ThunderPhone CLI kan clientconfiguratie schrijven met behoud van niet-gerelateerde servers:

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

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.
Selecteer Verbinden, log in bij ThunderPhone, kies de organisatie en keur de machtigingen goed.
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

Als ThunderPhone in de ChatGPT-appdirectory staat, selecteer je het en maak je verbinding.
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.
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.

Claude Code

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:

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

Cursor

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

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

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

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

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