---
title: "Používajte ThunderPhone ako server MCP"
description: "Vytvárajte, testujte, overujte a prevádzkujte hlasových agentov ThunderPhone z Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code alebo iného klienta Streamable HTTP MCP."
---

ThunderPhone poskytuje server Streamable HTTP Model Context Protocol na adrese:

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

Ide o opačný smer než pri [pripojení vzdialeného servera MCP k hlasovému agentovi](/sk/guides/mcp-servers):

| Smer | Výsledok |
| --- | --- |
| Vzdialený server MCP → agent ThunderPhone | Hlasový agent môže volať nástroje vzdialeného servera. |
| ThunderPhone → váš klient MCP | Váš kódovací agent môže vytvárať, testovať a spravovať ThunderPhone. |

## Overenie totožnosti

Pre klientov z adresára predvolene použite [OAuth](/sk/guides/oauth): prihláste sa, vyberte organizáciu a schváľte požadované oprávnenia. Prístup odvolajte v časti **Organizácia → Kľúče API → Autorizované aplikácie**.

Pre klientov nakonfigurovaných pomocou kľúča API vytvorte kľúč `sk_live_` v časti **Organizácia → Kľúče** a sprístupnite ho klientovi MCP ako `THUNDERPHONE_API_KEY`. Kľúč je viazaný na jednu organizáciu; identifikátor vlastnený inou organizáciou sa správa, akoby nebol nájdený.

<Warning>
  Kľúč `sk_live_` môže čítať údaje organizácie a vykonávať produkčné akcie, ako je nasadzovanie agentov, uskutočňovanie hovorov, nákup čísel, spúšťanie kampaní a odstraňovanie zdrojov. Neukladajte ho do kódu prehliadača, repozitárov, snímok obrazovky ani záznamov chatu. Použite úložisko tajomstiev alebo podporu prostredia vášho klienta a odhalený kľúč okamžite odvolajte.
</Warning>

## Alternatívy CLI a stdio

[ThunderPhone CLI](/sk/guides/cli) môže zapisovať konfiguráciu klienta pri zachovaní
nesúvisiacich serverov:

```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álnej inštalácii `@thunderphone/mcp` použite `thunderphone-mcp setup` s
rovnakými možnosťami. Nastavenie podporuje Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop a Windsurf. Uprednostňuje sa priame HTTP; Desktop používa stdio.

Pre ľubovoľného klienta podporujúceho stdio nakonfigurujte `command: "npx"` s
`args: ["-y", "@thunderphone/mcp"]`. Obal najskôr používa `THUNDERPHONE_API_KEY`,
potom poverenia z príkazu `thunderphone login`, pričom obnovuje tokeny po uplynutí platnosti, a následne
OAuth prostredníctvom `mcp-remote`. Prihlásenie zariadenia a OAuth vyžadujú príslušné zavedenie
OAuth v API. Cesta s kľúčom API ho nevyžaduje. Konfigurácie priameho HTTP nečítajú
úložisko poverení CLI; na opätovné použitie prihlásenia zariadenia použite obal stdio.

Tieto možnosti sú alternatívou k manuálnym konfiguráciám klienta uvedeným nižšie.

## Konfigurácia klienta

Claude a ChatGPT používajú prihlásenie cez [OAuth](/sk/guides/oauth); nepoužíva sa žiadny kľúč API. Ak ešte nemáte účet ThunderPhone, na prihlasovacej stránke vyberte **Vytvoriť účet**. Po overení e-mailu sa vrátite na obrazovku schválenia.

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

1. Otvorte **Nastavenia → Konektory**. Ak sa ThunderPhone zobrazí v adresári konektorov, vyberte ho. V opačnom prípade vyberte **Pridať vlastný konektor**, pomenujte ho `ThunderPhone` a zadajte `https://api.thunderphone.com/v1/mcp`.
2. Vyberte **Pripojiť**, prihláste sa do ThunderPhone, vyberte organizáciu a schváľte oprávnenia.
3. V chate povoľte ThunderPhone v ponuke nástrojov a požiadajte o to, čo potrebujete, napríklad „Zobraziť zoznam mojich agentov“.

Vlastné konektory vyžadujú platený program Claude. V programoch Team a Enterprise vlastník najprv pridá konektor v nastaveniach konektorov organizácie a potom si každý člen pripojí vlastný účet ThunderPhone.

### ChatGPT

1. Ak sa ThunderPhone zobrazí v adresári aplikácií ChatGPT, vyberte ho a pripojte sa.
2. V opačnom prípade otvorte **Nastavenia → Aplikácie a konektory → Rozšírené nastavenia**, zapnite **Režim vývojára** a vytvorte konektor s adresou URL `https://api.thunderphone.com/v1/mcp` a overovaním OAuth.
3. Prihláste sa do ThunderPhone, vyberte organizáciu a schváľte oprávnenia. Pridajte ThunderPhone do chatu z ponuky nástrojov.

Odstránenie agenta alebo telefónneho čísla, zahodenie konceptu a spustenie kampane vyžadujú v oboch aplikáciách druhé potvrdenie; pozrite si [Potvrdzovanie deštruktívnych akcií](#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

Pridajte toto do súboru `~/.codex/config.toml`:

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

### Cursor

Vytvorte súbor `.cursor/mcp.json`:

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

### Claude Desktop

Pridajte most `mcp-remote` do konfigurácie 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

Vytvorte súbor `.vscode/mcp.json` a zadajte kľúč prostredníctvom výzvy na zadanie vo 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 anotácie MCP. V tabuľkách **R** znamená iba na čítanie, **D** deštruktívny, **I** idempotentný a **O** interakciu s otvoreným svetom alebo sieťou. Pomlčka znamená, že nie je nastavená žiadna nápoveda.

### Agenti

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Vypíše agentov. |
| `get_agent` | `agent_id` | R, I | Získa jedného agenta. |
| `create_agent` | konfigurácia agenta | — | Vytvorí agenta. |
| `update_agent` | `agent_id`, zmenené polia | — | Pripraví polia v návrhu agenta. |
| `deploy_agent` | `agent_id`, voliteľné `if_updated_at` | I | Presunie návrh do produkcie. |
| `discard_agent_draft` | `agent_id`, voliteľné `if_updated_at`, `confirmation_token` pri druhej požiadavke | D, I | Zahodí pripravené zmeny. Dvojkrokový postup, pozrite si [Potvrdzovanie deštruktívnych akcií](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, voliteľné `name` | — | Skopíruje agenta v rámci organizácie. |
| `delete_agent` | `agent_id`, `confirmation_token` pri druhej požiadavke | D, I | Natrvalo odstráni agenta. Dvojkrokový postup. |
| `list_agent_versions` | `agent_id` | R, I | Vypíše nasadené verzie konfigurácie. |

### Telefónne čísla a operátori

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Vypíše čísla organizácie a smerovanie. |
| `get_phone_number_limits` | — | R, I | Získa využitie a limity spravovaných čísel. |
| `provision_phone_number` | voliteľné `area_code`, `city`, `state`, `idempotency_key` | O | Kúpi prichádzajúce číslo spravované službou ThunderPhone. |
| `list_voip_connections` | — | R, I | Vypíše pripojených operátorov zákazníka. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, voliteľné `area_code` | R, I, O | Vyhľadáva v inventári operátora. |
| `import_voip_numbers` | `connection_id`, `numbers` | O | Importuje čísla, ktoré už vlastníte u operátora. |
| `update_phone_number` | `phone_number_id`, polia smerovania/označenia/webhooku | — | Aktualizuje smerovanie čísla vrátane priradenia agenta. |
| `delete_phone_number` | `phone_number_id`, `confirm`, voliteľné `release_at_provider`, `confirmation_token` pri druhej požiadavke | D, I, O | Uvoľní číslo. Dvojkrokový postup. |

### Hovory

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_calls` | voliteľné filtre, `limit`, `offset` | R, I | Vypíše hovory s filtrami histórie hovorov REST. |
| `get_call` | `call_id` | R, I | Získa stav hovoru a metadáta. |
| `get_call_transcript` | `call_id`, voliteľné `live` | R, I | Získa prepis hovoru. |
| `get_call_audio_url` | `call_id`, voliteľné `download` | R, I, O | Vráti podpísanú adresu URL zvuku; nikdy neprenáša zvuk cez MCP. |
| `get_call_grade` | `call_id` | R, I | Získa najnovšie hodnotenie hovoru. |
| `place_call` | `agent_id`, `from_number`, `to_number` | O | Uskutoční jeden neidempotentný odchádzajúci hovor. |
| `export_calls` | filtre hovorov, `export_format` | R, I | Exportuje až do limitu koncového bodu REST vo formáte JSON alebo CSV. |

### Testovanie a overovanie

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Vypíše testovacie scenáre. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, voliteľné podmienky | — | Vytvorí scenár. |
| `generate_test_scenarios` | `agent_id`, voliteľné `count`, `include_edge_cases`, `locale` | O | Generuje scenáre z výzvy agenta. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, voliteľný výber/matica | O | Spustí scenáre cez web alebo telefóniu. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Získa stav dávky a výsledky jednotlivých scenárov. |
| `list_validation_runs` | `agent_id` | R, I | Vypíše nedávne spustenia overenia návrhu. |
| `get_validation_status` | `agent_id` | R, I | Získa najnovší stav overenia a zhodu návrhu. |

### Znalosti

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Vypíše znalostné databázy. |
| `create_knowledge_base` | `name`, voliteľné `description` | — | Vytvorí znalostnú databázu. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Pridá text alebo Markdown. |
| `import_knowledge_url` | `url`, voliteľné `name` | O | Zaradí verejnú stránku do frontu na bezpečné spracovanie. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Vyhľadáva prostredníctvom produkčného získavania informácií. |

### Integrácie, webhooky a vzdialené servery MCP

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Vypíše integrácie funkcií HTTP. |
| `create_integration` | `display_name`, funkcia `spec`, voliteľné polia koncového bodu | — | Vytvorí nástroj HTTP. |
| `test_integration` | `url`, voliteľné method/headers/body/timeout | O | Odošle obmedzenú testovaciu požiadavku chránenú pred SSRF. |
| `list_webhook_endpoints` | — | R, I | Vypíše podpísané koncové body webhookov. |
| `create_webhook_endpoint` | `label`, `url`, voliteľné events/status | O | Vytvorí podpísaný koncový bod webhooku. |
| `test_webhook_endpoint` | `endpoint_id` | O | Odošle syntetickú udalosť prostredníctvom bežného doručovania. |
| `list_mcp_servers` | — | R, I | Vypíše vzdialené servery, ktoré môžu volať hlasoví agenti. |
| `create_mcp_server` | `display_name`, `url`, voliteľné headers | O | Zaregistruje a synchronizuje vzdialený server. |
| `sync_mcp_server_tools` | `server_id` | O | Obnoví katalóg nástrojov vzdialeného servera. |

### Kampane

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Vypíše odchádzajúce kampane. |
| `create_campaign` | polia kampane | — | Vytvorí návrh kampane. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Pridá až 5 000 kontaktov JSON. |
| `campaign_action` | `campaign_id`, `action`, voliteľné `consent_to_charge`, `confirmation_token` pri druhej požiadavke | D, O | Spustí `start`, `pause`, `resume` alebo `stop`. `start` a `resume` sú dvojkrokové; `pause` a `stop` sa spustia okamžite. |
| `get_campaign_stats` | `campaign_id` | R, I | Získa počítadlá a nedávne výsledky. |

### Hlasy, fakturácia, importy a dokumentácia

| Nástroj | Hlavné argumenty | Anotácie | Čo robí |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Vypíše hlasy a podporované jazyky. |
| `preview_voice` | `voice`, `language`, `text` | O | Vygeneruje ukážku a vráti podpísanú adresu URL. |
| `list_voice_clones` | — | R, I | Vypíše vlastné klony hlasov. |
| `get_billing_summary` | — | R, I | Získa zostatok a záväzné ceny úrovní; nie sú sprístupnené žiadne zmeny platieb. |
| `create_agent_import` | `vendor`, `vendor_key` | O | Spustí šifrovaný import z Vapi, Retell, ElevenLabs alebo Bland. |
| `get_agent_import` | `public_id` | R, I | Získa navrhovaný rozdiel importu. |
| `commit_agent_import` | `public_id` | — | Potvrdí vybraných agentov z kontrolovaného plánu. |
| `search_docs` | `query`, voliteľné `limit` | R, I, O | Vyhľadáva vo verejnom indexe dokumentácie. |
| `get_doc_page` | `path` | R, I, O | Načíta jednu verejnú stránku dokumentácie Markdown. |

Všetky produktové nástroje používajú rovnaké cesty kódu REST ako verejné API. Overovanie REST, rozsah organizácie, roly, schvaľovanie fakturácie, kvóty, potvrdenie TCPA, bezpečnosť poskytovateľov a správanie auditu preto platia bez zmeny.

## Potvrdzovanie deštruktívnych akcií

Nástroje označené D menia alebo odstraňujú niečo, čo nemožno obnoviť, alebo začínajú vytáčať skutočné osoby. Vyžadujú dve požiadavky. Prvá požiadavka nič nemení a vráti:

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

Asistent používateľovi zobrazí, čo bude ovplyvnené, a požiada o potvrdenie. Potom zopakuje požiadavku s rovnakými argumentmi a s parametrom `confirmation_token`. Token je platný 10 minút a vzťahuje sa na jednu organizáciu, jeden nástroj a jednu presnú sadu argumentov, takže odstránenie troch agentov vyžaduje tri potvrdenia. `campaign_action` s hodnotou `pause` alebo `stop` tento krok preskočí, aby bolo možné prebiehajúcu kampaň vždy okamžite zastaviť.

## Úvodné prompty

`prompts/list` ponúka šesť opakovane použiteľných pracovných postupov:

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

Použite `prompts/get` s uvedeným názvom promptu a jeho deklarovanými argumentmi, aby ste získali správu používateľa pripravenú na spustenie.

## Zdroje

`resources/list` sprístupňuje verejné referencie uložené vo vyrovnávacej pamäti:

| URI | Obsah |
| --- | --- |
| `thunderphone://docs/llms.txt` | Verejný index dokumentácie. |
| `thunderphone://docs/quickstart` | Markdown s rýchlym začiatkom. |
| `thunderphone://pricing` | Markdown s aktuálnymi verejnými cenami. |

Jeden zdroj načítajte pomocou `resources/read`. Verejné načítania používajú krátky časový limit, limit 2 MiB a desaťminútovú vyrovnávaciu pamäť v procese.

## Protokol a chyby

Server podporuje verzie protokolu `2025-06-18` a `2025-03-26`; vráti podporovanú verziu klienta a inak vyberie `2025-06-18`. Implementuje `initialize`, `ping`, nástroje, prompty, zdroje a oznámenia. Oznámenia vracajú `202 Accepted`. Tento bezstavový server nesprístupňuje poslucháč SSE ani odstránenie relácie, takže `GET` a `DELETE` vracajú `405 Method Not Allowed` s hodnotou `Allow: POST`.

Zlyhania nástrojov zostávajú úspešnými odpoveďami JSON-RPC s hodnotou `isError: true`. Ich text obsahuje krátku vetu, po ktorej nasleduje blok 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."
}
```

Rozlišovací prefix `outbound_tcpa_confirmation_required:` zostáva zachovaný pre `place_call`. Neznáme metódy JSON-RPC vracajú `-32601` v odpovedi HTTP `200`. Dávky JSON-RPC nie sú podporované v MCP `2025-06-18` a vracajú čistú chybu neplatnej požiadavky `-32600`.