---
title: "ThunderPhone als MCP-Server verwenden"
description: "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:

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

Dies ist die entgegengesetzte Richtung zu [einem mit einem Sprachagenten verbundenen Remote-MCP-Server](/de/guides/mcp-servers):

| 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](/de/guides/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.

<Warning>
  Ein `sk_live_`-Schlüssel kann Organisationsdaten lesen und Produktionsaktionen ausführen, etwa Agenten bereitzellen, Anrufe tätigen, Nummern kaufen, Kampagnen starten und Ressourcen löschen. Halten Sie ihn aus Browsercode, Repositories, Screenshots und Chatprotokollen heraus. Verwenden Sie den Geheimnisspeicher oder die Umgebungsunterstützung Ihres Clients und widerrufen Sie einen offengelegten Schlüssel sofort.
</Warning>

## CLI- und stdio-Alternativen

Die [ThunderPhone CLI](/de/guides/cli) kann die Client-Konfiguration schreiben und dabei
nicht verwandte Server beibehalten:

```bash
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](/de/guides/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)

1. Ö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.
2. Wählen Sie **Verbinden**, melden Sie sich bei ThunderPhone an, wählen Sie die Organisation aus und genehmigen Sie die Berechtigungen.
3. 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

1. Wenn ThunderPhone im ChatGPT-App-Verzeichnis angezeigt wird, wählen Sie es aus und verbinden Sie es.
2. 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.
3. 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](#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

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

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

### Cursor

Erstellen Sie `.cursor/mcp.json`:

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

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

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

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

## 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](#confirming-destructive-actions). |
| `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:

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

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