---
title: "Používejte ThunderPhone jako server MCP"
description: "Vytvářejte, testujte, ověřujte a provozujte hlasové agenty ThunderPhone z Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code nebo jiného klienta Streamable HTTP MCP."
---

ThunderPhone poskytuje server Streamable HTTP Model Context Protocol na adrese:

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

Jde o opačný směr než při [připojení vzdáleného serveru MCP k hlasovému agentovi](/cs/guides/mcp-servers):

| Směr | Výsledek |
| --- | --- |
| Vzdálený server MCP → agent ThunderPhone | Hlasový agent může volat nástroje vzdáleného serveru. |
| ThunderPhone → váš klient MCP | Váš programovací agent může ThunderPhone vytvářet, testovat a provozovat. |

## Ověření

Pro klienty z adresáře ve výchozím nastavení použijte [OAuth](/cs/guides/oauth): přihlaste se, vyberte organizaci a schvalte požadovaná oprávnění. Přístup odeberte v části **Organizace → Klíče API → Autorizované aplikace**.

Pro klienty nakonfigurované pomocí klíče API vytvořte klíč `sk_live_` v části **Organizace → Klíče** a zpřístupněte jej klientovi MCP jako `THUNDERPHONE_API_KEY`. Klíč je vázán na jednu organizaci; ID vlastněné jinou organizací se chová, jako by nebylo nalezeno.

<Warning>
  Klíč `sk_live_` může číst data organizace a provádět produkční akce, například nasazovat agenty, uskutečňovat hovory, kupovat čísla, spouštět kampaně a odstraňovat prostředky. Neumisťujte jej do kódu prohlížeče, repozitářů, snímků obrazovky ani protokolů chatu. Použijte úložiště tajných údajů nebo podporu proměnných prostředí ve svém klientovi a odhalený klíč ihned odvolejte.
</Warning>

## Alternativy CLI a stdio

Rozhraní [ThunderPhone CLI](/cs/guides/cli) může zapsat konfiguraci klienta a zároveň zachovat
nesouvisející servery:

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

Po globální instalaci `@thunderphone/mcp` použijte `thunderphone-mcp setup` se
stejnými možnostmi. Nastavení podporuje Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop a Windsurf. Upřednostňuje se přímé HTTP; Desktop používá stdio.

Pro libovolného klienta podporujícího stdio nakonfigurujte `command: "npx"` s
`args: ["-y", "@thunderphone/mcp"]`. Obal nejprve používá `THUNDERPHONE_API_KEY`,
poté přihlašovací údaje z `thunderphone login`, obnovuje tokeny po vypršení platnosti a následně
OAuth prostřednictvím `mcp-remote`. Přihlášení zařízení a OAuth vyžadují odpovídající zavedení
OAuth rozhraní API. Cesta s klíčem API jej nevyžaduje. Konfigurace přímého HTTP nečtou
úložiště přihlašovacích údajů CLI; pro opětovné použití přihlášení zařízení použijte obal stdio.

Jedná se o alternativy k ručním konfiguracím klientů níže.

## Konfigurace klienta

Claude a ChatGPT se přihlašují pomocí [OAuth](/cs/guides/oauth); žádný klíč API se nepoužívá. Pokud ještě nemáte účet ThunderPhone, na přihlašovací stránce zvolte **Vytvořit účet** a po ověření e-mailu se vrátíte na obrazovku schválení.

### Claude (web, počítač a mobil)

1. Otevřete **Přizpůsobit → Konektory** (ve starších verzích **Nastavení → Konektory**). Pokud se ThunderPhone zobrazí v katalogu konektorů, vyberte jej. Jinak zvolte **Přidat vlastní konektor**, pojmenujte jej `ThunderPhone` a zadejte `https://api.thunderphone.com/v1/mcp`.
2. Vyberte **Připojit**, přihlaste se do ThunderPhone, vyberte organizaci a schvalte oprávnění.
3. V chatu zapněte ThunderPhone v nabídce nástrojů a požádejte o to, co potřebujete, například „Vypiš moje agenty“.

Claude se před prvním použitím každého nástroje zeptá na potvrzení. Chcete-li většinu těchto výzev přeskočit, otevřete **Přizpůsobit → Konektory → ThunderPhone** a u možnosti **Nástroje jen pro čtení** nastavte vždy povolit. Tyto nástroje pouze vyhledávají informace: agenty, hovory, přepisy, zůstatky a dokumentaci. Pokud chcete vidět každou změnu před jejím provedením, ponechte u **Nástrojů pro zápis/odstranění** vyžadování schválení.

Vlastní konektory vyžadují placený tarif Claude. U tarifů Team a Enterprise vlastník nejprve přidá konektor v nastavení konektorů organizace a poté si každý člen připojí vlastní účet ThunderPhone.

### ChatGPT

1. Pokud se ThunderPhone zobrazí v katalogu aplikací ChatGPT, vyberte jej a připojte.
2. Jinak otevřete **Nastavení → Aplikace a konektory → Pokročilá nastavení**, zapněte **Režim pro vývojáře** a vytvořte konektor s adresou URL `https://api.thunderphone.com/v1/mcp` a ověřováním OAuth.
3. Přihlaste se do ThunderPhone, vyberte organizaci a schvalte oprávnění. Přidejte ThunderPhone do chatu z nabídky nástrojů.

Odstranění agenta nebo telefonního čísla, zahození konceptu, spuštění kampaně a odeslání testovacího požadavku, který může zapisovat do externího systému, vyžadují v obou aplikacích druhé potvrzení; viz [Potvrzování destruktivních akcí](#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

Přidejte toto do `~/.codex/config.toml`:

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

### Cursor

Vytvořte `.cursor/mcp.json`:

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

### Claude Desktop

Přidejte most `mcp-remote` do konfigurace 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

Vytvořte `.vscode/mcp.json` a zadejte klíč prostřednictvím výzvy k zadání ve 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}"
      }
    }
  }
}
```

## Nástroje

Každý nástroj obsahuje anotace MCP. V tabulkách **R** znamená pouze pro čtení, **D** destruktivní, **I** idempotentní a **O** interakci s externím světem nebo sítí. Pomlčka znamená, že není nastavena žádná nápověda.

### Připojení

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Ověří přihlašovací údaje a vrátí organizaci a bezpečná metadata přihlašovacích údajů. |

### Agenti

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Vypíše agenty. |
| `get_agent` | `agent_id` | R, I | Získá jednoho agenta. |
| `create_agent` | konfigurace agenta | — | Vytvoří agenta. |
| `update_agent` | `agent_id`, změněná pole | D | Uloží pole do konceptu agenta a nahradí tím, co koncept obsahoval. Spustí se bez kroku potvrzení: nasazený agent zůstane nezměněn až do `deploy_agent` a `discard_agent_draft` vrátí koncept zpět. |
| `deploy_agent` | `agent_id`, volitelné `if_updated_at` | D, I | Povýší koncept do produkce. |
| `discard_agent_draft` | `agent_id`, volitelné `if_updated_at`, `confirmation_token` při druhém požadavku | D, I | Zahodí připravené změny. Dvoufázové, viz [Potvrzování destruktivních akcí](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, volitelné `name` | — | Zkopíruje agenta v rámci organizace. |
| `delete_agent` | `agent_id`, `confirmation_token` při druhém požadavku | D, I | Trvale odstraní agenta. Dvoufázové. |
| `list_agent_versions` | `agent_id` | R, I | Vypíše nasazené verze konfigurace. |

### Telefonní čísla a operátoři

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Vypíše čísla organizace a směrování. |
| `get_phone_number_limits` | — | R, I | Získá využití a limity spravovaných čísel. |
| `provision_phone_number` | volitelné `area_code`, `city`, `state`, `idempotency_key` | D, O | Zakoupí příchozí číslo spravované službou ThunderPhone. |
| `list_voip_connections` | — | R, I | Vypíše připojené operátory zákazníka. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, volitelné `area_code` | R, I, O | Vyhledá v inventáři operátora. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importuje čísla, která již vlastníte u operátora. |
| `update_phone_number` | `phone_number_id`, pole směrování/popisku/webhooku | D | Aktualizuje směrování čísla včetně přiřazení agenta. |
| `delete_phone_number` | `phone_number_id`, `confirm`, volitelné `release_at_provider`, `confirmation_token` při druhém požadavku | D, I, O | Uvolní číslo. Dvoukrokové. |

### SMS

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Odešle jednu textovou SMS prostřednictvím připojeného čísla Twilio nebo Telnyx. |

### Hovory

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_calls` | volitelné filtry, `limit`, `offset` | R, I | Vypíše hovory s použitím filtrů historie hovorů REST. |
| `get_call` | `call_id` | R, I | Získá stav hovoru a metadata. |
| `get_call_transcript` | `call_id`, volitelný `live` | R, I | Získá přepis hovoru. |
| `get_call_audio_url` | `call_id`, volitelný `download` | R, I, O | Vrátí podepsanou adresu URL zvuku; zvuk nikdy nestreamuje prostřednictvím MCP. |
| `get_call_grade` | `call_id` | R, I | Získá nejnovější hodnocení hovoru. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Zahájí jeden neidempotentní odchozí hovor. |
| `export_calls` | filtry hovorů, `export_format` | R, I | Exportuje až do limitu koncového bodu REST ve formátu JSON nebo CSV. |

### Testování a ověřování

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Vypíše testovací scénáře. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, volitelné podmínky | — | Vytvoří scénář. |
| `generate_test_scenarios` | `agent_id`, volitelné `count`, `include_edge_cases`, `locale` | O | Vygeneruje scénáře z promptu agenta. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, volitelný výběr/matice | D, O | Spustí scénáře přes web nebo telefonii. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Získá stav dávky a výsledky jednotlivých scénářů. |
| `list_validation_runs` | `agent_id` | R, I | Vypíše nedávná spuštění ověření konceptu. |
| `get_validation_status` | `agent_id` | R, I | Získá nejnovější stav ověření a shodu konceptu. |

### Znalosti

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Vypíše znalostní báze. |
| `create_knowledge_base` | `name`, volitelné `description` | — | Vytvoří znalostní bázi. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Přidá text nebo Markdown. |
| `import_knowledge_url` | `url`, volitelné `name` | O | Zařadí veřejnou stránku do fronty pro bezpečné zpracování. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Vyhledá v produkčním získávání informací. |

### Integrace, webhooky a vzdálené servery MCP

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Vypíše integrace funkcí HTTP. |
| `create_integration` | `display_name`, specifikace funkce `spec`, volitelná pole koncového bodu | — | Vytvoří nástroj HTTP. Hlavičky ověřování přidejte v ovládacím panelu. |
| `test_integration` | `url`, volitelná metoda/tělo/časový limit, `integration_id` s `header_names`, `confirmation_token` při druhém požadavku | D, O | Odešle omezený testovací požadavek chráněný proti SSRF. Uložené hodnoty hlaviček se doplní z integrace a odešlou se pouze jejímu vlastnímu hostiteli. `POST` (výchozí), `PUT`, `PATCH` a `DELETE` jsou dvoukrokové; `GET` se spustí okamžitě. |
| `list_webhook_endpoints` | — | R, I | Vypíše podepsané koncové body webhooků. |
| `list_webhook_deliveries` | volitelné `agent_id`, volitelné `endpoint_id` | R, I | Vypíše nedávné výsledky doručení webhooků bez datových částí. |
| `create_webhook_endpoint` | `label`, `url`, volitelné události/stav | O | Vytvoří podepsaný koncový bod webhooku. |
| `test_webhook_endpoint` | `endpoint_id` | O | Odešle syntetickou událost prostřednictvím běžného doručení. |
| `list_mcp_servers` | — | R, I | Vypíše vzdálené servery, které mohou volat hlasoví agenti. |
| `create_mcp_server` | `display_name`, `url` | O | Zaregistruje a synchronizuje vzdálený server. Servery, které vyžadují ověřovací hlavičky, přidejte v ovládacím panelu. |
| `sync_mcp_server_tools` | `server_id` | D, O | Obnoví katalog nástrojů vzdáleného serveru. |

### Kampaně

| Nástroj | Hlavní argumenty | Anotace | Co dělá |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Vypíše odchozí kampaně. |
| `create_campaign` | pole kampaně | — | Vytvoří koncept kampaně. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Přidá až 5 000 kontaktů JSON. |
| `campaign_action` | `campaign_id`, `action`, volitelné `consent_to_charge`, `confirmation_token` při druhém požadavku | D, O | Spustí `start`, `pause`, `resume` nebo `stop`. `start` a `resume` jsou dvoukrokové; `pause` a `stop` se spustí okamžitě. |
| `get_campaign_stats` | `campaign_id` | R, I | Získá čítače a nedávné výsledky. |

### Hlasy, fakturace a dokumentace

| Nástroj | Hlavní argumenty | Poznámky | Co dělá |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Vypíše hlasy a podporované jazyky. |
| `preview_voice` | `voice`, `language`, `text` | O | Vygeneruje ukázku a vrátí podepsanou adresu URL. |
| `list_voice_clones` | — | R, I | Vypíše vlastní klony hlasů. |
| `get_billing_summary` | — | R, I | Získá zůstatek a závazné ceny tarifních úrovní; neumožňuje žádné změny plateb. |
| `search_docs` | `query`, volitelný `limit` | R, I, O | Prohledá veřejný index dokumentace. |
| `get_doc_page` | `path` | R, I, O | Načte jednu veřejnou stránku dokumentace ve formátu Markdown. |

Všechny produktové nástroje používají stejné cesty kódu REST jako veřejné API. Ověřování REST, vymezení organizace, role, povolení fakturace, kvóty, potvrzení TCPA, bezpečnost poskytovatelů a chování auditu proto platí beze změny.

## Potvrzování destruktivních akcí

Nástroje označené D něco mění nebo odstraňují, případně zahajují vytáčení skutečným lidem. Ty, které nelze vrátit zpět, vyžadují dva požadavky. První požadavek nic nemění a vrátí:

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

Asistent uživateli ukáže, čeho se akce týká, a požádá o potvrzení. Poté požadavek zopakuje se stejnými argumenty a přidá `confirmation_token`. Token je platný 10 minut a vztahuje se na jednu organizaci, jeden nástroj a jednu přesnou sadu argumentů, takže odstranění tří agentů vyžaduje tři potvrzení. `campaign_action` s `pause` nebo `stop` tento krok přeskočí, aby bylo možné probíhající kampaň vždy okamžitě zastavit, stejně jako `test_integration` s `GET`. Některé nástroje D se spouštějí jedním požadavkem, protože D označuje jejich účinek, nikoli potvrzení na straně serveru: `update_agent` nahradí obsah návrhu (`discard_agent_draft` jej vrátí zpět), `deploy_agent` nahradí aktivní konfiguraci, `update_phone_number` přesměruje probíhající hovory, `sync_mcp_server_tools` nahradí katalog nástrojů vzdáleného serveru, `import_voip_numbers` přesměruje čísla k vašemu operátorovi, `run_agent_tests` může spotřebovat kredit, `send_sms` a `place_call` kontaktují skutečnou osobu (`place_call` zachovává vlastní potvrzení souhlasu) a `provision_phone_number` zakoupí číslo. Váš klient MCP vás přesto může požádat o jejich schválení.

## Úvodní prompty

`prompts/list` nabízí pět znovupoužitelných pracovních postupů:

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

Pomocí `prompts/get` s uvedeným názvem promptu a jeho deklarovanými argumenty získáte připravenou uživatelskou zprávu ke spuštění.

## Zdroje

`resources/list` zpřístupňuje veřejné referenční zdroje uložené v mezipaměti:

| URI | Obsah |
| --- | --- |
| `thunderphone://docs/llms.txt` | Veřejný index dokumentace. |
| `thunderphone://docs/quickstart` | Markdown pro rychlý začátek. |
| `thunderphone://pricing` | Aktuální veřejný Markdown s cenami. |

Jeden zdroj načtěte pomocí `resources/read`. Veřejná načítání používají krátký časový limit, limit 2 MiB a desetiminutovou mezipaměť v procesu.

## Protokol a chyby

Server podporuje verze protokolu `2025-06-18` a `2025-03-26`; vrací podporovanou verzi klienta a v ostatních případech vybere `2025-06-18`. Implementuje `initialize`, `ping`, nástroje, prompty, zdroje a oznámení. Oznámení vracejí `202 Accepted`. Tento bezstavový server nezpřístupňuje posluchač SSE ani odstranění relace, takže `GET` a `DELETE` vracejí `405 Method Not Allowed` s `Allow: POST`.

Selhání nástrojů zůstávají úspěšnými odpověďmi JSON-RPC s `isError: true`. Jejich text obsahuje krátkou větu následovanou blokem 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."
}
```

Pro `place_call` zůstává zachována odlišná předpona `outbound_tcpa_confirmation_required:`. Neznámé metody JSON-RPC vracejí `-32601` v odpovědi HTTP `200`. Dávky JSON-RPC nejsou podporovány protokolem MCP `2025-06-18` a vracejí čistou chybu neplatného požadavku `-32600`.