Open in

Używaj ThunderPhone jako serwera MCP

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:

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

Jest to kierunek odwrotny do łączenia zdalnego serwera MCP z agentem głosowym:

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

Alternatywy CLI i stdio

CLI ThunderPhone może zapisać konfigurację klienta, zachowując niepowiązane serwery:

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; 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)

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.
Wybierz Połącz, zaloguj się do ThunderPhone, wybierz organizację i zatwierdź uprawnienia.
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

Jeśli ThunderPhone znajduje się w katalogu aplikacji ChatGPT, wybierz go i połącz.
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.
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.

Claude Code

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:

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

Cursor

Utwórz .cursor/mcp.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:

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

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

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

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