--- title: "Używaj ThunderPhone jako serwera MCP" description: "Twórz, testuj, weryfikuj i obsługuj agentów głosowych ThunderPhone z poziomu Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code lub innego klienta Streamable HTTP MCP." --- ThunderPhone udostępnia serwer Model Context Protocol z obsługą Streamable HTTP pod adresem: ```text https://api.thunderphone.com/v1/mcp ``` Jest to kierunek odwrotny do [łączenia zdalnego serwera MCP z agentem głosowym](/pl/guides/mcp-servers): | Kierunek | Wynik | | --- | --- | | Zdalny serwer MCP → agent ThunderPhone | Agent głosowy może wywoływać narzędzia zdalnego serwera. | | ThunderPhone → Twój klient MCP | Twój agent programistyczny może tworzyć, testować i obsługiwać ThunderPhone. | ## Uwierzytelnianie Domyślnie używaj [OAuth](/pl/guides/oauth) w przypadku klientów katalogowych: zaloguj się, wybierz organizację i zatwierdź żądane uprawnienia. Odbierz dostęp w **Organizacja → Klucze API → Autoryzowane aplikacje**. W przypadku klientów skonfigurowanych z kluczem API utwórz klucz `sk_live_` w **Organizacja → Klucze** i udostępnij go klientowi MCP jako `THUNDERPHONE_API_KEY`. Klucz jest przypisany do jednej organizacji; identyfikator należący do innej organizacji zachowuje się tak, jakby nie został znaleziony. Klucz `sk_live_` może odczytywać dane organizacji i wykonywać działania produkcyjne, takie jak wdrażanie agentów, inicjowanie połączeń, kupowanie numerów, uruchamianie kampanii i usuwanie zasobów. Nie umieszczaj go w kodzie przeglądarkowym, repozytoriach, zrzutach ekranu ani logach czatu. Użyj magazynu sekretów lub obsługi zmiennych środowiskowych klienta i natychmiast unieważnij ujawniony klucz. ## Alternatywy CLI i stdio [CLI ThunderPhone](/pl/guides/cli) może zapisać konfigurację klienta, zachowując niepowiązane serwery: ```bash npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY npx thunderphone mcp setup --client claude-desktop --scope user ``` Po globalnej instalacji `@thunderphone/mcp` użyj `thunderphone-mcp setup` z tymi samymi opcjami. Konfiguracja obsługuje Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop i Windsurf. Preferowane jest bezpośrednie HTTP; Claude Desktop używa stdio. Dla dowolnego klienta obsługującego stdio skonfiguruj `command: "npx"` z `args: ["-y", "@thunderphone/mcp"]`. Wrapper najpierw używa `THUNDERPHONE_API_KEY`, następnie poświadczeń z `thunderphone login`, odświeżając wygasłe tokeny, a potem OAuth przez `mcp-remote`. Logowanie urządzenia i OAuth wymagają wdrożenia odpowiedniej funkcji OAuth API. Ścieżka z kluczem API tego nie wymaga. Bezpośrednie konfiguracje HTTP nie odczytują magazynu poświadczeń CLI; użyj wrappera stdio, aby ponownie wykorzystać logowanie urządzenia. Są to alternatywy dla ręcznych konfiguracji klientów poniżej. ## Konfiguracja klienta Claude i ChatGPT logują się za pomocą [OAuth](/pl/guides/oauth); nie jest wymagany klucz API. Jeśli nie masz jeszcze konta ThunderPhone, wybierz **Utwórz konto** na stronie logowania, a po zweryfikowaniu adresu e-mail wrócisz do ekranu zatwierdzania. ### Claude (wersja internetowa, komputerowa i mobilna) 1. Otwórz **Dostosuj → Łączniki** (**Ustawienia → Łączniki** w starszych wersjach). Jeśli ThunderPhone znajduje się w katalogu łączników, wybierz go. W przeciwnym razie wybierz **Dodaj niestandardowy łącznik**, nadaj mu nazwę `ThunderPhone` i wpisz `https://api.thunderphone.com/v1/mcp`. 2. Wybierz **Połącz**, zaloguj się do ThunderPhone, wybierz organizację i zatwierdź uprawnienia. 3. Na czacie włącz ThunderPhone z menu narzędzi i poproś o to, czego potrzebujesz, na przykład „Wyświetl moich agentów”. Claude pyta o zgodę przed pierwszym użyciem każdego narzędzia. Aby pominąć większość tych monitów, otwórz **Dostosuj → Łączniki → ThunderPhone** i ustaw opcję **Narzędzia tylko do odczytu** na zawsze zezwalaj. Te narzędzia jedynie wyszukują informacje: agentów, połączenia, transkrypcje, salda i dokumentację. Pozostaw opcję **Narzędzia zapisu/usuwania** jako wymagającą zatwierdzenia, jeśli chcesz zobaczyć każdą zmianę, zanim zostanie wprowadzona. Niestandardowe łączniki wymagają płatnego planu Claude. W planach Team i Enterprise właściciel najpierw dodaje łącznik w ustawieniach łączników organizacji, a następnie każdy członek łączy własne konto ThunderPhone. ### ChatGPT 1. Jeśli ThunderPhone znajduje się w katalogu aplikacji ChatGPT, wybierz go i połącz. 2. W przeciwnym razie otwórz **Ustawienia → Aplikacje i łączniki → Ustawienia zaawansowane**, włącz **Tryb dewelopera** i utwórz łącznik z adresem URL `https://api.thunderphone.com/v1/mcp` oraz uwierzytelnianiem OAuth. 3. Zaloguj się do ThunderPhone, wybierz organizację i zatwierdź uprawnienia. Dodaj ThunderPhone do czatu z menu narzędzi. Usunięcie agenta lub numeru telefonu, odrzucenie wersji roboczej, uruchomienie kampanii i wysłanie żądania testowego, które może zapisywać dane w systemie zewnętrznym, wymagają drugiego potwierdzenia w obu aplikacjach; zobacz [Potwierdzanie działań destrukcyjnych](#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 Dodaj poniższe do `~/.codex/config.toml`: ```toml [mcp_servers.thunderphone] url = "https://api.thunderphone.com/v1/mcp" bearer_token_env_var = "THUNDERPHONE_API_KEY" ``` ### Cursor Utwórz `.cursor/mcp.json`: ```json { "mcpServers": { "thunderphone": { "url": "https://api.thunderphone.com/v1/mcp", "headers": { "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}" } } } } ``` ### Claude Desktop Dodaj most `mcp-remote` do konfiguracji 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 Utwórz `.vscode/mcp.json` i wprowadź klucz za pomocą monitu wejściowego 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}" } } } } ``` ## Narzędzia Każde narzędzie zawiera adnotacje MCP. W tabelach **R** oznacza tylko do odczytu, **D** działanie niszczące, **I** idempotentność, a **O** interakcję ze światem zewnętrznym/siecią. Myślnik oznacza, że nie ustawiono żadnej wskazówki. ### Połączenie | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `get_connection_identity` | — | R, I | Weryfikuje poświadczenie i zwraca organizację oraz bezpieczne metadane poświadczenia. | ### Agenci | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_agents` | — | R, I | Wyświetla listę agentów. | | `get_agent` | `agent_id` | R, I | Pobiera jednego agenta. | | `create_agent` | konfiguracja agenta | — | Tworzy agenta. | | `update_agent` | `agent_id`, zmienione pola | D | Przygotowuje pola w wersji roboczej agenta, zastępując wcześniejszą zawartość wersji roboczej. Działa bez kroku potwierdzenia: wdrożony agent pozostaje bez zmian do czasu użycia `deploy_agent`, a `discard_agent_draft` przywraca poprzedni stan wersji roboczej. | | `deploy_agent` | `agent_id`, opcjonalne `if_updated_at` | D, I | Promuje wersję roboczą do produkcji. | | `discard_agent_draft` | `agent_id`, opcjonalne `if_updated_at`, `confirmation_token` przy drugim żądaniu | D, I | Odrzuca przygotowane zmiany. Proces dwuetapowy, zobacz [Potwierdzanie działań destrukcyjnych](#confirming-destructive-actions). | | `duplicate_agent` | `agent_id`, opcjonalne `name` | — | Kopiuje agenta w organizacji. | | `delete_agent` | `agent_id`, `confirmation_token` przy drugim żądaniu | D, I | Trwale usuwa agenta. Proces dwuetapowy. | | `list_agent_versions` | `agent_id` | R, I | Wyświetla listę wdrożonych wersji konfiguracji. | ### Numery telefonów i operatorzy | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_phone_numbers` | — | R, I | Wyświetla numery organizacji i routing. | | `get_phone_number_limits` | — | R, I | Pobiera wykorzystanie i limity zarządzanych numerów. | | `provision_phone_number` | opcjonalne `area_code`, `city`, `state`, `idempotency_key` | D, O | Kupuje numer przychodzący zarządzany przez ThunderPhone. | | `list_voip_connections` | — | R, I | Wyświetla połączonych operatorów klienta. | | `search_voip_numbers` | `connection_id`, `country`, `type`, opcjonalne `area_code` | R, I, O | Przeszukuje zasoby numerów operatora. | | `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importuje numery należące już do operatora. | | `update_phone_number` | `phone_number_id`, pola routingu/etykiety/webhooka | D | Aktualizuje routing numeru, w tym przypisanie agenta. | | `delete_phone_number` | `phone_number_id`, `confirm`, opcjonalne `release_at_provider`, `confirmation_token` w drugim żądaniu | D, I, O | Zwalnia numer. Dwuetapowo. | ### SMS | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Wysyła jedną wiadomość SMS w postaci zwykłego tekstu przez połączony numer Twilio lub Telnyx. | ### Połączenia | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_calls` | opcjonalne filtry, `limit`, `offset` | R, I | Wyświetla połączenia z użyciem filtrów historii połączeń REST. | | `get_call` | `call_id` | R, I | Pobiera status połączenia i metadane. | | `get_call_transcript` | `call_id`, opcjonalne `live` | R, I | Pobiera transkrypcję połączenia. | | `get_call_audio_url` | `call_id`, opcjonalne `download` | R, I, O | Zwraca podpisany adres URL audio; nigdy nie przesyła strumieniowo dźwięku przez MCP. | | `get_call_grade` | `call_id` | R, I | Pobiera najnowszą ocenę połączenia. | | `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Wykonuje jedno nieidempotentne połączenie wychodzące. | | `export_calls` | filtry połączeń, `export_format` | R, I | Eksportuje dane do limitu punktu końcowego REST w formacie JSON lub CSV. | ### Testowanie i walidacja | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_test_scenarios` | `agent_id` | R, I | Wyświetla scenariusze testowe. | | `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, opcjonalne warunki | — | Tworzy scenariusz. | | `generate_test_scenarios` | `agent_id`, opcjonalne `count`, `include_edge_cases`, `locale` | O | Generuje scenariusze na podstawie promptu agenta. | | `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, opcjonalny wybór/macierz | D, O | Uruchamia scenariusze przez internet lub telefonię. | | `get_test_run` | `agent_id`, `batch_id` | R, I | Pobiera status partii i wyniki dla każdego scenariusza. | | `list_validation_runs` | `agent_id` | R, I | Wyświetla ostatnie uruchomienia walidacji wersji roboczej. | | `get_validation_status` | `agent_id` | R, I | Pobiera najnowszy stan walidacji i dopasowanie wersji roboczej. | ### Wiedza | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_knowledge_bases` | — | R, I | Wyświetla bazy wiedzy. | | `create_knowledge_base` | `name`, opcjonalne `description` | — | Tworzy bazę wiedzy. | | `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Dodaje tekst lub Markdown. | | `import_knowledge_url` | `url`, opcjonalne `name` | O | Kolejkuje publiczną stronę do bezpiecznego pozyskania treści. | | `search_knowledge` | `knowledge_base_id`, `query` | R, I | Wyszukuje w produkcyjnym systemie pobierania wiedzy. | ### Integracje, webhooki i zdalne serwery MCP | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_integrations` | — | R, I | Wyświetla integracje funkcji HTTP. | | `create_integration` | `display_name`, `spec` funkcji, opcjonalne pola punktu końcowego | — | Tworzy narzędzie HTTP. Dodaj nagłówki uwierzytelniania w panelu. | | `test_integration` | `url`, opcjonalne metoda/treść/limit czasu, `integration_id` z `header_names`, `confirmation_token` w drugim żądaniu | D, O | Wysyła ograniczone żądanie testowe chronione przed SSRF. Zapisane wartości nagłówków są uzupełniane z integracji i wysyłane tylko do jej własnego hosta. `POST` (domyślnie), `PUT`, `PATCH` i `DELETE` są dwuetapowe; `GET` uruchamia się od razu. | | `list_webhook_endpoints` | — | R, I | Wyświetla podpisane punkty końcowe webhooków. | | `list_webhook_deliveries` | opcjonalne `agent_id`, opcjonalne `endpoint_id` | R, I | Wyświetla ostatnie wyniki dostarczania webhooków bez ładunków. | | `create_webhook_endpoint` | `label`, `url`, opcjonalne zdarzenia/status | O | Tworzy podpisany punkt końcowy webhooka. | | `test_webhook_endpoint` | `endpoint_id` | O | Wysyła syntetyczne zdarzenie poprzez standardowe dostarczanie. | | `list_mcp_servers` | — | R, I | Wyświetla zdalne serwery wywoływalne przez agentów głosowych. | | `create_mcp_server` | `display_name`, `url` | O | Rejestruje i synchronizuje zdalny serwer. Serwery wymagające nagłówków uwierzytelniania dodaje się w panelu. | | `sync_mcp_server_tools` | `server_id` | D, O | Odświeża katalog narzędzi zdalnego serwera. | ### Kampanie | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_campaigns` | — | R, I | Wyświetla kampanie wychodzące. | | `create_campaign` | pola kampanii | — | Tworzy wersję roboczą kampanii. | | `add_campaign_contacts` | `campaign_id`, `contacts` | — | Dodaje do 5 000 kontaktów JSON. | | `campaign_action` | `campaign_id`, `action`, opcjonalne `consent_to_charge`, `confirmation_token` w drugim żądaniu | D, O | Uruchamia `start`, `pause`, `resume` lub `stop`. `start` i `resume` wymagają dwóch kroków; `pause` i `stop` są uruchamiane natychmiast. | | `get_campaign_stats` | `campaign_id` | R, I | Pobiera liczniki i ostatnie wyniki. | ### Głosy, rozliczenia i dokumentacja | Narzędzie | Główne argumenty | Adnotacje | Działanie | | --- | --- | --- | --- | | `list_voices` | — | R, I | Wyświetla głosy i obsługiwane języki. | | `preview_voice` | `voice`, `language`, `text` | O | Generuje próbkę i zwraca podpisany adres URL. | | `list_voice_clones` | — | R, I | Wyświetla niestandardowe klony głosu. | | `get_billing_summary` | — | R, I | Pobiera saldo i wiążące ceny poziomów; nie udostępnia operacji modyfikujących płatności. | | `search_docs` | `query`, opcjonalny `limit` | R, I, O | Przeszukuje publiczny indeks dokumentacji. | | `get_doc_page` | `path` | R, I, O | Pobiera jedną publiczną stronę dokumentacji w formacie Markdown. | Wszystkie narzędzia produktowe używają tych samych ścieżek kodu REST co publiczne API. Walidacja REST, zakres organizacji, role, dopuszczanie rozliczeń, limity, potwierdzenie TCPA, bezpieczeństwo dostawcy i zachowanie audytu mają zatem zastosowanie bez zmian. ## Potwierdzanie działań destrukcyjnych Narzędzia oznaczone symbolem D zmieniają lub usuwają coś albo rozpoczynają wybieranie numerów do prawdziwych osób. Te, których nie można cofnąć, wymagają dwóch żądań. Pierwsze żądanie niczego nie zmienia i zwraca: ```json { "status": "confirmation_required", "action": "Delete agent", "target": { "id": 195, "name": "Front Desk Receptionist" }, "confirmation_token": "…", "expires_in_seconds": 600, "next_step": "…" } ``` Asystent pokazuje użytkownikowi, czego dotyczy działanie, i prosi o potwierdzenie. Następnie powtarza żądanie z tymi samymi argumentami oraz `confirmation_token`. Token jest ważny przez 10 minut i obejmuje jedną organizację, jedno narzędzie oraz jeden dokładny zestaw argumentów, więc usunięcie trzech agentów wymaga trzech potwierdzeń. `campaign_action` z `pause` lub `stop` pomija ten krok, aby aktywną kampanię można było zawsze natychmiast zatrzymać, podobnie jak `test_integration` z `GET`. Niektóre narzędzia D działają w jednym żądaniu, ponieważ D oznacza ich skutek, a nie potwierdzenie po stronie serwera: `update_agent` zastępuje zawartość wersji roboczej (`discard_agent_draft` ją przywraca), `deploy_agent` zastępuje aktywną konfigurację, `update_phone_number` przekierowuje aktywne połączenia, `sync_mcp_server_tools` zastępuje katalog narzędzi zdalnego serwera, `import_voip_numbers` przekierowuje numery do operatora, `run_agent_tests` może wykorzystać środki, `send_sms` i `place_call` kontaktują się z prawdziwą osobą (`place_call` zachowuje własne potwierdzenie zgody), a `provision_phone_number` kupuje numer. Klient MCP może nadal poprosić o zatwierdzenie tych działań. ## Prompty startowe `prompts/list` udostępnia pięć przepływów pracy wielokrotnego użytku: - `create_inbound_receptionist` - `run_agent_tests` - `buy_and_attach_number` - `review_low_grade_calls` - `add_url_to_agent_knowledge` Użyj `prompts/get` z nazwą wymienionego promptu i jego zadeklarowanymi argumentami, aby otrzymać gotową do uruchomienia wiadomość użytkownika. ## Zasoby `resources/list` udostępnia publiczne, buforowane odwołania: | URI | Zawartość | | --- | --- | | `thunderphone://docs/llms.txt` | Indeks publicznej dokumentacji. | | `thunderphone://docs/quickstart` | Markdown szybkiego startu. | | `thunderphone://pricing` | Markdown z aktualnym publicznym cennikiem. | Odczytaj zasób za pomocą `resources/read`. Publiczne pobrania używają krótkiego limitu czasu, limitu 2 MiB oraz dziesięciominutowej pamięci podręcznej w procesie. ## Protokół i błędy Serwer obsługuje wersje protokołu `2025-06-18` i `2025-03-26`; odzwierciedla obsługiwaną wersję klienta, a w przeciwnym razie wybiera `2025-06-18`. Implementuje `initialize`, `ping`, narzędzia, prompty, zasoby i powiadomienia. Powiadomienia zwracają `202 Accepted`. Ten bezstanowy serwer nie udostępnia nasłuchiwania SSE ani usuwania sesji, dlatego `GET` i `DELETE` zwracają `405 Method Not Allowed` z `Allow: POST`. Niepowodzenia narzędzi pozostają pomyślnymi odpowiedziami JSON-RPC z `isError: true`. Ich tekst zawiera krótkie zdanie, po którym następuje 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." } ``` Charakterystyczny prefiks `outbound_tcpa_confirmation_required:` jest zachowywany dla `place_call`. Nieznane metody JSON-RPC zwracają `-32601` w odpowiedzi HTTP `200`. Partie JSON-RPC nie są obsługiwane przez MCP `2025-06-18` i zwracają jednoznaczny błąd nieprawidłowego żądania `-32600`.