Open in

ThunderPhone als MCP-Server verwenden

ThunderPhone-Sprachagenten über Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code oder einen anderen Streamable-HTTP-MCP-Client erstellen, testen, validieren und betreiben.

ThunderPhone stellt unter folgender Adresse einen Streamable-HTTP-Server für das Model Context Protocol bereit:

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

Dies ist die entgegengesetzte Richtung zu einem mit einem Sprachagenten verbundenen Remote-MCP-Server:

Richtung	Ergebnis
Remote-MCP-Server → ThunderPhone-Agent	Ein Sprachagent kann die Tools des Remote-Servers aufrufen.
ThunderPhone → Ihr MCP-Client	Ihr Programmieragent kann ThunderPhone erstellen, testen und betreiben.

Authentifizieren

Verwenden Sie für Verzeichnis-Clients standardmäßig OAuth: Melden Sie sich an, wählen Sie eine Organisation aus und genehmigen Sie die angeforderten Berechtigungen. Widerrufen Sie den Zugriff unter Organisation → API-Schlüssel → Autorisierte Apps.

Erstellen Sie für Clients, die mit einem API-Schlüssel konfiguriert sind, unter Organisation → Schlüssel einen sk_live_-Schlüssel und stellen Sie ihn Ihrem MCP-Client als THUNDERPHONE_API_KEY bereit. Der Schlüssel ist an eine Organisation gebunden; eine ID, die einer anderen Organisation gehört, verhält sich wie nicht gefunden.

CLI- und stdio-Alternativen

Die ThunderPhone CLI kann die Client-Konfiguration schreiben und dabei nicht verwandte Server beibehalten:

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

Nach einer globalen Installation von @thunderphone/mcp verwenden Sie thunderphone-mcp setup mit denselben Optionen. Die Einrichtung unterstützt Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop und Windsurf. Direktes HTTP wird bevorzugt; Desktop verwendet stdio.

Konfigurieren Sie für jeden stdio-fähigen Client command: "npx" mit args: ["-y", "@thunderphone/mcp"]. Der Wrapper verwendet zuerst THUNDERPHONE_API_KEY, anschließend Anmeldedaten aus thunderphone login, erneuert abgelaufene Tokens und verwendet dann OAuth über mcp-remote. Geräteanmeldung und OAuth erfordern die entsprechende OAuth-Einführung der API. Der API-Schlüsselpfad nicht. Direkte HTTP-Konfigurationen lesen nicht den Anmeldedatenspeicher der CLI; verwenden Sie den stdio-Wrapper, um die Geräteanmeldung erneut zu nutzen.

Dies sind Alternativen zu den manuellen Client-Konfigurationen unten.

Client-Konfiguration

Claude und ChatGPT melden sich über OAuth an; es ist kein API-Schlüssel erforderlich. Wenn Sie noch kein ThunderPhone-Konto haben, wählen Sie auf der Anmeldeseite Konto erstellen. Nach der Bestätigung Ihrer E-Mail-Adresse kehren Sie zum Genehmigungsbildschirm zurück.

Claude (Web, Desktop und Mobilgeräte)

Öffnen Sie Anpassen → Konnektoren (in älteren Versionen Einstellungen → Konnektoren). Wenn ThunderPhone im Konnektorenverzeichnis angezeigt wird, wählen Sie es aus. Andernfalls wählen Sie Benutzerdefinierten Konnektor hinzufügen, benennen ihn ThunderPhone und geben https://api.thunderphone.com/v1/mcp ein.
Wählen Sie Verbinden, melden Sie sich bei ThunderPhone an, wählen Sie die Organisation aus und genehmigen Sie die Berechtigungen.
Aktivieren Sie ThunderPhone in einem Chat über das Tool-Menü und fragen Sie nach dem, was Sie benötigen, zum Beispiel „Meine Agenten auflisten“.

Claude fragt, bevor es jedes Tool zum ersten Mal verwendet. Um die meisten dieser Abfragen zu überspringen, öffnen Sie Anpassen → Konnektoren → ThunderPhone und setzen Sie Schreibgeschützte Tools auf immer zulassen. Diese Tools fragen nur Informationen ab: Agenten, Anrufe, Transkripte, Guthaben, Docs. Lassen Sie Schreib-/Löschtools auf Genehmigung, wenn Sie jede Änderung sehen möchten, bevor sie erfolgt.

Benutzerdefinierte Konnektoren erfordern einen kostenpflichtigen Claude-Tarif. Bei Team- und Enterprise-Tarifen fügt ein Inhaber den Konnektor zuerst in den Konnektoreinstellungen der Organisation hinzu. Anschließend verbindet jedes Mitglied sein eigenes ThunderPhone-Konto.

ChatGPT

Wenn ThunderPhone im ChatGPT-App-Verzeichnis angezeigt wird, wählen Sie es aus und verbinden Sie es.
Andernfalls öffnen Sie Einstellungen → Apps & Konnektoren → Erweiterte Einstellungen, aktivieren Sie den Entwicklermodus und erstellen Sie einen Konnektor mit der URL https://api.thunderphone.com/v1/mcp und OAuth-Authentifizierung.
Melden Sie sich bei ThunderPhone an, wählen Sie die Organisation aus und genehmigen Sie die Berechtigungen. Fügen Sie ThunderPhone über das Tool-Menü zu einem Chat hinzu.

Das Löschen eines Agenten oder einer Telefonnummer, das Verwerfen eines Entwurfs, das Starten einer Kampagne und das Senden einer Testanfrage, die in ein externes System schreiben kann, erfordern in beiden Apps eine zweite Bestätigung; siehe Zerstörerische Aktionen bestätigen.

Claude Code

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

Codex

Fügen Sie dies zu ~/.codex/config.toml hinzu:

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

Cursor

Erstellen Sie .cursor/mcp.json:

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

Claude Desktop

Fügen Sie der Claude-Desktop-Konfiguration eine mcp-remote-Bridge hinzu:

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

Erstellen Sie .vscode/mcp.json und geben Sie den Schlüssel über die Eingabeaufforderung von VS Code ein:

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

Tools

Jedes Tool enthält MCP-Anmerkungen. In den Tabellen bedeutet R schreibgeschützt, D destruktiv, I idempotent und O Interaktion mit der offenen Welt bzw. dem Netzwerk. Ein Gedankenstrich bedeutet, dass kein Hinweis festgelegt ist.

Verbindung

Tool	Hauptargumente	Anmerkungen	Funktion
`get_connection_identity`	—	R, I	Validiert die Zugangsdaten und gibt die zugehörige Organisation sowie sichere Metadaten zu den Zugangsdaten zurück.

Agenten

Tool	Hauptargumente	Anmerkungen	Funktion
`list_agents`	—	R, I	Listet Agenten auf.
`get_agent`	`agent_id`	R, I	Ruft einen Agenten ab.
`create_agent`	Agentenkonfiguration	—	Erstellt einen Agenten.
`update_agent`	`agent_id`, geänderte Felder	D	Stellt Felder im Agentenentwurf bereit und ersetzt dabei die bisherigen Werte des Entwurfs. Wird ohne Bestätigungsschritt ausgeführt: Der bereitgestellte Agent bleibt unverändert, bis `deploy_agent` ausgeführt wird, und `discard_agent_draft` setzt den Entwurf zurück.
`deploy_agent`	`agent_id`, optional `if_updated_at`	D, I	Übernimmt den Entwurf in die Produktion.
`discard_agent_draft`	`agent_id`, optional `if_updated_at`, `confirmation_token` bei der zweiten Anfrage	D, I	Verwirft bereitgestellte Änderungen. In zwei Schritten, siehe Bestätigung destruktiver Aktionen.
`duplicate_agent`	`agent_id`, optional `name`	—	Kopiert einen Agenten innerhalb der Organisation.
`delete_agent`	`agent_id`, `confirmation_token` bei der zweiten Anfrage	D, I	Löscht einen Agenten dauerhaft. In zwei Schritten.
`list_agent_versions`	`agent_id`	R, I	Listet bereitgestellte Konfigurationsversionen auf.

Telefonnummern und Carrier

Tool	Hauptargumente	Anmerkungen	Funktion
`list_phone_numbers`	—	R, I	Listet Organisationsnummern und Routing auf.
`get_phone_number_limits`	—	R, I	Ruft Nutzung und Limits verwalteter Nummern ab.
`provision_phone_number`	optional `area_code`, `city`, `state`, `idempotency_key`	D, O	Kauft eine von ThunderPhone verwaltete eingehende Nummer.
`list_voip_connections`	—	R, I	Listet verbundene Kundenanbieter auf.
`search_voip_numbers`	`connection_id`, `country`, `type`, optional `area_code`	R, I, O	Durchsucht den Bestand des Anbieters.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Importiert Nummern, die bereits dem Anbieter gehören.
`update_phone_number`	`phone_number_id`, Routing-/Label-/Webhook-Felder	D	Aktualisiert das Nummern-Routing, einschließlich der Agentenzuweisung.
`delete_phone_number`	`phone_number_id`, `confirm`, optional `release_at_provider`, `confirmation_token` bei der zweiten Anfrage	D, I, O	Gibt eine Nummer frei. Zwei Schritte.

SMS

Tool	Hauptargumente	Anmerkungen	Funktion
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Sendet eine reine Text-SMS über eine verbundene Twilio- oder Telnyx-Nummer.

Anrufe

Tool	Hauptargumente	Anmerkungen	Funktion
`list_calls`	optionale Filter, `limit`, `offset`	R, I	Listet Anrufe mit den REST-Filtern für den Anrufverlauf auf.
`get_call`	`call_id`	R, I	Ruft Anrufstatus und Metadaten ab.
`get_call_transcript`	`call_id`, optional `live`	R, I	Ruft das Anruftranskript ab.
`get_call_audio_url`	`call_id`, optional `download`	R, I, O	Gibt eine signierte Audio-URL zurück; Audio wird niemals über MCP gestreamt.
`get_call_grade`	`call_id`	R, I	Ruft die neueste Anrufbewertung ab.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Tätigt einen nicht-idempotenten ausgehenden Anruf.
`export_calls`	Anruffilter, `export_format`	R, I	Exportiert bis zur Begrenzung des REST-Endpunkts als JSON oder CSV.

Tests und Validierung

Tool	Hauptargumente	Anmerkungen	Funktion
`list_test_scenarios`	`agent_id`	R, I	Listet Testszenarien auf.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, optionale Bedingungen	—	Erstellt ein Szenario.
`generate_test_scenarios`	`agent_id`, optional `count`, `include_edge_cases`, `locale`	O	Generiert Szenarien aus dem Agenten-Prompt.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, optionale Auswahl/Matrix	D, O	Führt Szenarien über das Web oder die Telefonie aus.
`get_test_run`	`agent_id`, `batch_id`	R, I	Ruft den Batch-Status und Ergebnisse pro Szenario ab.
`list_validation_runs`	`agent_id`	R, I	Listet aktuelle Validierungsläufe für Entwürfe auf.
`get_validation_status`	`agent_id`	R, I	Ruft den neuesten Validierungsstatus und die Entwurfsübereinstimmung ab.

Wissen

Tool	Hauptargumente	Anmerkungen	Funktion
`list_knowledge_bases`	—	R, I	Listet Wissensdatenbanken auf.
`create_knowledge_base`	`name`, optional `description`	—	Erstellt eine Wissensdatenbank.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Fügt Text oder Markdown hinzu.
`import_knowledge_url`	`url`, optional `name`	O	Stellt eine öffentliche Seite für die sichere Aufnahme in die Warteschlange.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Durchsucht die Produktionsabfrage.

Integrationen, Webhooks und Remote-MCP-Server

Tool	Hauptargumente	Anmerkungen	Funktion
`list_integrations`	—	R, I	Listet HTTP-Funktionsintegrationen auf.
`create_integration`	`display_name`, Funktions-`spec`, optionale Endpunktfelder	—	Erstellt ein HTTP-Tool. Fügen Sie Authentifizierungs-Header im Dashboard hinzu.
`test_integration`	`url`, optionale Methode/Body/Timeout, `integration_id` mit `header_names`, `confirmation_token` bei der zweiten Anfrage	D, O	Sendet eine begrenzte, SSRF-geschützte Testanfrage. Gespeicherte Header-Werte werden aus der Integration übernommen und nur an deren eigenen Host gesendet. `POST` (der Standard), `PUT`, `PATCH` und `DELETE` erfolgen in zwei Schritten; `GET` wird sofort ausgeführt.
`list_webhook_endpoints`	—	R, I	Listet signierte Webhook-Endpunkte auf.
`list_webhook_deliveries`	optionale `agent_id`, optionale `endpoint_id`	R, I	Listet aktuelle Ergebnisse von Webhook-Zustellungen ohne Payload auf.
`create_webhook_endpoint`	`label`, `url`, optionale Ereignisse/Status	O	Erstellt einen signierten Webhook-Endpunkt.
`test_webhook_endpoint`	`endpoint_id`	O	Sendet ein synthetisches Ereignis über die normale Zustellung.
`list_mcp_servers`	—	R, I	Listet Remote-Server auf, die von Sprachagenten aufgerufen werden können.
`create_mcp_server`	`display_name`, `url`	O	Registriert und synchronisiert einen Remote-Server. Server, die Authentifizierungs-Header benötigen, werden im Dashboard hinzugefügt.
`sync_mcp_server_tools`	`server_id`	D, O	Aktualisiert den Tool-Katalog eines Remote-Servers.

Kampagnen

Tool	Hauptargumente	Anmerkungen	Funktion
`list_campaigns`	—	R, I	Listet ausgehende Kampagnen auf.
`create_campaign`	Kampagnenfelder	—	Erstellt einen Kampagnenentwurf.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Fügt bis zu 5.000 JSON-Kontakte hinzu.
`campaign_action`	`campaign_id`, `action`, optional `consent_to_charge`, `confirmation_token` bei der zweiten Anfrage	D, O	Führt `start`, `pause`, `resume` oder `stop` aus. `start` und `resume` erfolgen in zwei Schritten; `pause` und `stop` werden sofort ausgeführt.
`get_campaign_stats`	`campaign_id`	R, I	Ruft Zähler und aktuelle Ergebnisse ab.

Stimmen, Abrechnung und Docs

Werkzeug	Hauptargumente	Anmerkungen	Funktion
`list_voices`	—	R, I	Listet Stimmen und unterstützte Sprachen auf.
`preview_voice`	`voice`, `language`, `text`	O	Erstellt ein Beispiel und gibt eine signierte URL zurück.
`list_voice_clones`	—	R, I	Listet benutzerdefinierte Stimmklone auf.
`get_billing_summary`	—	R, I	Ruft Guthaben und maßgebliche Preise der Tarifstufen ab; es sind keine Zahlungsänderungen verfügbar.
`search_docs`	`query`, optional `limit`	R, I, O	Durchsucht den öffentlichen Docs-Index.
`get_doc_page`	`path`	R, I, O	Ruft eine öffentliche Markdown-Dokumentationsseite ab.

Alle Produkt-Tools verwenden dieselben REST-Codepfade wie die öffentliche API. REST-Validierung, Organisationsabgrenzung, Rollen, Abrechnungszulassung, Kontingente, TCPA-Bestätigung, Provider-Sicherheit und Auditverhalten gelten daher unverändert.

Bestätigung destruktiver Aktionen

Mit D gekennzeichnete Tools ändern oder entfernen etwas oder beginnen, echte Personen anzuwählen. Vorgänge, die nicht rückgängig gemacht werden können, erfordern zwei Anfragen. Die erste Anfrage ändert nichts und gibt Folgendes zurück:

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

Der Assistent zeigt dem Benutzer, was betroffen ist, und bittet um eine Bestätigung. Anschließend wiederholt er die Anfrage mit denselben Argumenten sowie confirmation_token. Ein Token ist 10 Minuten gültig und gilt für eine Organisation, ein Tool und einen exakten Satz von Argumenten. Daher erfordert das Löschen von drei Agenten drei Bestätigungen. campaign_action mit pause oder stop überspringt diesen Schritt, damit eine laufende Kampagne jederzeit sofort angehalten werden kann. Dasselbe gilt für test_integration mit GET. Einige D-Tools werden mit einer Anfrage ausgeführt, weil das D ihre Wirkung kennzeichnet und keine serverseitige Bestätigung: update_agent ersetzt den Inhalt des Entwurfs (discard_agent_draft setzt ihn zurück), deploy_agent ersetzt die aktive Konfiguration, update_phone_number leitet aktive Anrufe um, sync_mcp_server_tools ersetzt den Toolkatalog eines Remote-Servers, import_voip_numbers leitet Nummern auf Ihren Anbieter um, run_agent_tests kann Guthaben verbrauchen, send_sms und place_call erreichen eine echte Person (place_call behält seine eigene Einwilligungsbestätigung bei) und provision_phone_number kauft eine Nummer. Ihr MCP-Client kann Sie weiterhin bitten, diese zu genehmigen.

Starter-Prompts

prompts/list stellt fünf wiederverwendbare Workflows bereit:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Verwenden Sie prompts/get mit dem aufgeführten Prompt-Namen und den angegebenen Argumenten, um eine sofort ausführbare Benutzernachricht zu erhalten.

Ressourcen

resources/list stellt öffentliche, zwischengespeicherte Referenzen bereit:

URI	Inhalt
`thunderphone://docs/llms.txt`	Index der öffentlichen Dokumentation.
`thunderphone://docs/quickstart`	Quickstart-Markdown.
`thunderphone://pricing`	Aktuelles öffentliches Preis-Markdown.

Lesen Sie eine Ressource mit resources/read. Öffentliche Abrufe verwenden ein kurzes Timeout, ein Limit von 2 MiB und einen prozessinternen Cache mit zehn Minuten Laufzeit.

Protokoll und Fehler

Der Server unterstützt die Protokollversionen 2025-06-18 und 2025-03-26; er gibt eine unterstützte Client-Version zurück und wählt andernfalls 2025-06-18. Er implementiert initialize, ping, Tools, Prompts, Ressourcen und Benachrichtigungen. Benachrichtigungen geben 202 Accepted zurück. Dieser zustandslose Server stellt weder einen SSE-Listener noch das Löschen von Sitzungen bereit. Daher geben GET und DELETE 405 Method Not Allowed mit Allow: POST zurück.

Tool-Fehler bleiben erfolgreiche JSON-RPC-Antworten mit isError: true. Ihr Text enthält einen kurzen Satz, gefolgt von einem JSON-Block:

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

Das eindeutige Präfix outbound_tcpa_confirmation_required: bleibt für place_call erhalten. Unbekannte JSON-RPC-Methoden geben -32601 in einer HTTP-200-Antwort zurück. JSON-RPC-Batches werden von MCP 2025-06-18 nicht unterstützt und geben einen sauberen -32600-Fehler für ungültige Anfragen zurück.