Open in

Використовуйте ThunderPhone як MCP-сервер

Створюйте, тестуйте, перевіряйте та керуйте голосовими агентами ThunderPhone із Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code або іншого клієнта Streamable HTTP MCP.

ThunderPhone надає сервер Streamable HTTP Model Context Protocol за адресою:

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

Це протилежний напрямок до підключення віддаленого MCP-сервера до голосового агента:

Напрямок	Результат
Віддалений MCP-сервер → агент ThunderPhone	Голосовий агент може викликати інструменти віддаленого сервера.
ThunderPhone → ваш MCP-клієнт	Ваш агент для програмування може створювати, тестувати та керувати ThunderPhone.

Автентифікація

За замовчуванням використовуйте OAuth для клієнтів каталогу: увійдіть, виберіть організацію та схваліть запитувані дозволи. Відкликати доступ можна в розділі Організація → API-ключі → Авторизовані застосунки.

Для клієнтів, налаштованих з API-ключем, створіть ключ sk_live_ у розділі Організація → Ключі та надайте його MCP-клієнту як THUNDERPHONE_API_KEY. Ключ прив’язаний до однієї організації; ідентифікатор, що належить іншій організації, обробляється як не знайдений.

Альтернативи CLI та stdio

ThunderPhone CLI може записувати конфігурацію клієнта, зберігаючи непов’язані сервери:

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

Після глобального встановлення @thunderphone/mcp використовуйте thunderphone-mcp setup із тими самими параметрами. Налаштування підтримує Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop і Windsurf. Прямий HTTP є рекомендованим; Desktop використовує stdio.

Для будь-якого клієнта з підтримкою stdio налаштуйте command: "npx" з args: ["-y", "@thunderphone/mcp"]. Обгортка спершу використовує THUNDERPHONE_API_KEY, потім облікові дані з thunderphone login, оновлюючи прострочені токени, а потім OAuth через mcp-remote. Вхід через пристрій і OAuth потребують відповідного розгортання OAuth API. Шлях із API-ключем цього не потребує. Конфігурації прямого HTTP не читають сховище облікових даних CLI; використовуйте обгортку stdio для повторного використання входу через пристрій.

Це альтернативи ручним конфігураціям клієнта нижче.

Налаштування клієнта

Claude і ChatGPT входять через OAuth; ключ API не потрібен. Якщо у вас ще немає облікового запису ThunderPhone, виберіть Створити обліковий запис на сторінці входу, і після підтвердження електронної пошти ви повернетеся на екран надання дозволів.

Claude (вебверсія, настільна та мобільна версії)

Відкрийте Налаштувати → Конектори (Налаштування → Конектори у старіших версіях). Якщо ThunderPhone відображається в каталозі конекторів, виберіть його. Інакше виберіть Додати власний конектор, назвіть його ThunderPhone і введіть https://api.thunderphone.com/v1/mcp.
Виберіть Підключити, увійдіть до ThunderPhone, виберіть організацію та надайте дозволи.
У чаті увімкніть ThunderPhone в меню інструментів і сформулюйте свій запит, наприклад «Покажи список моїх агентів».

Claude запитує підтвердження перед першим використанням кожного інструмента. Щоб пропускати більшість таких запитів, відкрийте Налаштувати → Конектори → ThunderPhone і встановіть для Інструменти лише для читання значення завжди дозволяти. Ці інструменти лише переглядають дані: агентів, дзвінки, транскрипти, баланси, документацію. Залиште для Інструменти запису/видалення вимогу підтвердження, якщо хочете бачити кожну зміну до її виконання.

Для власних конекторів потрібен платний тариф Claude. У тарифах Team і Enterprise власник спочатку додає конектор у налаштуваннях конекторів організації, а потім кожен учасник підключає власний обліковий запис ThunderPhone.

ChatGPT

Якщо ThunderPhone відображається в каталозі застосунків ChatGPT, виберіть його та підключіться.
Інакше відкрийте Налаштування → Застосунки й конектори → Розширені налаштування, увімкніть Режим розробника та створіть конектор з URL https://api.thunderphone.com/v1/mcp і автентифікацією OAuth.
Увійдіть до ThunderPhone, виберіть організацію та надайте дозволи. Додайте ThunderPhone до чату з меню інструментів.

Видалення агента або номера телефону, скасування чернетки, запуск кампанії та надсилання тестового запиту, який може записувати дані до зовнішньої системи, потребують другого підтвердження в обох застосунках; див. Підтвердження руйнівних дій.

Claude Code

claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"

Codex

Додайте це до ~/.codex/config.toml:

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

Cursor

Створіть .cursor/mcp.json:

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

Claude Desktop

Додайте міст mcp-remote до конфігурації 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

Створіть .vscode/mcp.json і введіть ключ через запит введення 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}"
      }
    }
  }
}

Інструменти

Кожен інструмент має анотації MCP. У таблицях R означає лише читання, D — руйнівну дію, I — ідемпотентність, а O — взаємодію з відкритим світом/мережею. Тире означає, що підказку не встановлено.

Підключення

Інструмент	Основні аргументи	Анотації	Що робить
`get_connection_identity`	—	R, I	Перевіряє облікові дані та повертає дані про організацію й безпечні метадані облікових даних.

Агенти

Інструмент	Основні аргументи	Анотації	Призначення
`list_agents`	—	R, I	Перелічує агентів.
`get_agent`	`agent_id`	R, I	Отримує одного агента.
`create_agent`	конфігурація агента	—	Створює агента.
`update_agent`	`agent_id`, змінені поля	D	Зберігає поля в чернетці агента, замінюючи дані, що були в чернетці. Виконується без кроку підтвердження: розгорнутий агент не змінюється до `deploy_agent`, а `discard_agent_draft` скасовує зміни в чернетці.
`deploy_agent`	`agent_id`, необов’язковий `if_updated_at`	D, I	Переносить чернетку в продакшн.
`discard_agent_draft`	`agent_id`, необов’язковий `if_updated_at`, `confirmation_token` у другому запиті	D, I	Відкидає збережені зміни. Два кроки, див. Підтвердження руйнівних дій.
`duplicate_agent`	`agent_id`, необов’язковий `name`	—	Копіює агента в межах організації.
`delete_agent`	`agent_id`, `confirmation_token` у другому запиті	D, I	Остаточно видаляє агента. Два кроки.
`list_agent_versions`	`agent_id`	R, I	Перелічує версії розгорнутої конфігурації.

Номери телефонів і оператори зв’язку

Інструмент	Основні аргументи	Анотації	Що робить
`list_phone_numbers`	—	R, I	Перелічує номери організації та маршрутизацію.
`get_phone_number_limits`	—	R, I	Отримує використання та ліміти керованих номерів.
`provision_phone_number`	необов’язкові `area_code`, `city`, `state`, `idempotency_key`	D, O	Купує вхідний номер, керований ThunderPhone.
`list_voip_connections`	—	R, I	Перелічує підключених операторів клієнта.
`search_voip_numbers`	`connection_id`, `country`, `type`, необов’язковий `area_code`	R, I, O	Шукає в інвентарі оператора.
`import_voip_numbers`	`connection_id`, `numbers`	D, O	Імпортує номери, якими вже володіє оператор.
`update_phone_number`	`phone_number_id`, поля маршрутизації/мітки/webhook	D	Оновлює маршрутизацію номера, зокрема призначення агента.
`delete_phone_number`	`phone_number_id`, `confirm`, необов’язковий `release_at_provider`, `confirmation_token` у другому запиті	D, I, O	Вивільняє номер. Два кроки.

SMS

Інструмент	Основні аргументи	Анотації	Що робить
`send_sms`	`from_number`, `to`, `body`, `idempotency_key`	D, I, O	Надсилає одне текстове SMS через підключений номер Twilio або Telnyx.

Дзвінки

Інструмент	Основні аргументи	Анотації	Що робить
`list_calls`	необов’язкові фільтри, `limit`, `offset`	R, I	Перелічує дзвінки за допомогою REST-фільтрів історії дзвінків.
`get_call`	`call_id`	R, I	Отримує статус і метадані дзвінка.
`get_call_transcript`	`call_id`, необов’язковий `live`	R, I	Отримує транскрипт дзвінка.
`get_call_audio_url`	`call_id`, необов’язковий `download`	R, I, O	Повертає підписаний URL аудіо; ніколи не передає аудіо через MCP.
`get_call_grade`	`call_id`	R, I	Отримує останню оцінку дзвінка.
`place_call`	`agent_id`, `from_number`, `to_number`	D, O	Здійснює один неідемпотентний вихідний дзвінок.
`export_calls`	фільтри дзвінків, `export_format`	R, I	Експортує до ліміту REST-ендпойнта у форматі JSON або CSV.

Тестування та перевірка

Інструмент	Основні аргументи	Анотації	Що робить
`list_test_scenarios`	`agent_id`	R, I	Перелічує тестові сценарії.
`create_test_scenario`	`agent_id`, `title`, `scenario_prompt`, необов’язкові умови	—	Створює сценарій.
`generate_test_scenarios`	`agent_id`, необов’язкові `count`, `include_edge_cases`, `locale`	O	Генерує сценарії на основі промпту агента.
`run_agent_tests`	`agent_id`, `channel`, `consent_to_charge`, необов’язковий вибір/матриця	D, O	Виконує сценарії через веб або телефонію.
`get_test_run`	`agent_id`, `batch_id`	R, I	Отримує статус пакета та результати для кожного сценарію.
`list_validation_runs`	`agent_id`	R, I	Перелічує нещодавні запуски валідації чернеток.
`get_validation_status`	`agent_id`	R, I	Отримує найновіший стан валідації та відповідність чернетці.

База знань

Інструмент	Основні аргументи	Анотації	Що робить
`list_knowledge_bases`	—	R, I	Перелічує бази знань.
`create_knowledge_base`	`name`, необов’язковий `description`	—	Створює базу знань.
`add_knowledge_document`	`knowledge_base_id`, `name`, `content`	—	Додає текст або Markdown.
`import_knowledge_url`	`url`, необов’язковий `name`	O	Додає загальнодоступну сторінку в чергу для безпечного завантаження.
`search_knowledge`	`knowledge_base_id`, `query`	R, I	Шукає через пошук у продакшні.

Інтеграції, вебхуки та віддалені MCP-сервери

Інструмент	Основні аргументи	Анотації	Що робить
`list_integrations`	—	R, I	Перелічує інтеграції HTTP-функцій.
`create_integration`	`display_name`, специфікація функції `spec`, необов’язкові поля кінцевої точки	—	Створює HTTP-інструмент. Додайте заголовки автентифікації в панелі керування.
`test_integration`	`url`, необов’язкові метод/тіло/час очікування, `integration_id` із `header_names`, `confirmation_token` у другому запиті	D, O	Надсилає обмежений тестовий запит із захистом від SSRF. Збережені значення заголовків підставляються з інтеграції та надсилаються лише на її власний хост. `POST` (за замовчуванням), `PUT`, `PATCH` і `DELETE` виконуються у два кроки; `GET` виконується негайно.
`list_webhook_endpoints`	—	R, I	Перелічує підписані кінцеві точки вебхуків.
`list_webhook_deliveries`	необов’язковий `agent_id`, необов’язковий `endpoint_id`	R, I	Перелічує останні результати доставлення вебхуків без корисного навантаження.
`create_webhook_endpoint`	`label`, `url`, необов’язкові події/статус	O	Створює підписану кінцеву точку вебхука.
`test_webhook_endpoint`	`endpoint_id`	O	Надсилає синтетичну подію через звичайне доставлення.
`list_mcp_servers`	—	R, I	Перелічує віддалені сервери, які можуть викликати голосові агенти.
`create_mcp_server`	`display_name`, `url`	O	Реєструє та синхронізує віддалений сервер. Сервери, яким потрібні заголовки автентифікації, додаються в панелі керування.
`sync_mcp_server_tools`	`server_id`	D, O	Оновлює каталог інструментів віддаленого сервера.

Кампанії

Інструмент	Основні аргументи	Анотації	Що робить
`list_campaigns`	—	R, I	Перелічує вихідні кампанії.
`create_campaign`	поля кампанії	—	Створює чернетку кампанії.
`add_campaign_contacts`	`campaign_id`, `contacts`	—	Додає до 5 000 контактів JSON.
`campaign_action`	`campaign_id`, `action`, необов’язкові `consent_to_charge`, `confirmation_token` у другому запиті	D, O	Виконує `start`, `pause`, `resume` або `stop`. `start` і `resume` виконуються у два кроки; `pause` і `stop` виконуються негайно.
`get_campaign_stats`	`campaign_id`	R, I	Отримує лічильники та останні результати.

Голоси, виставлення рахунків і документація

Інструмент	Основні аргументи	Анотації	Призначення
`list_voices`	—	R, I	Виводить список голосів і підтримуваних мов.
`preview_voice`	`voice`, `language`, `text`	O	Генерує зразок і повертає підписаний URL.
`list_voice_clones`	—	R, I	Виводить список користувацьких клонів голосу.
`get_billing_summary`	—	R, I	Отримує баланс і актуальні ціни тарифів; зміни платежів недоступні.
`search_docs`	`query`, необов’язковий `limit`	R, I, O	Виконує пошук у загальнодоступному індексі документації.
`get_doc_page`	`path`	R, I, O	Завантажує одну загальнодоступну сторінку документації у Markdown.

Усі інструменти продукту використовують ті самі шляхи коду REST, що й загальнодоступний API. Тому перевірка REST, обмеження областю організації, ролі, допуск за виставленням рахунків, квоти, підтвердження TCPA, безпека постачальників і поведінка аудиту застосовуються без змін.

Підтвердження руйнівних дій

Інструменти, позначені D, змінюють або видаляють щось чи починають набір номера реальних людей. Для тих, які неможливо скасувати, потрібні два запити. Перший запит нічого не змінює та повертає:

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

Агент показує користувачеві, на що це вплине, і просить підтвердження. Потім він повторює запит із тими самими аргументами та confirmation_token. Токен дійсний протягом 10 хвилин і охоплює одну організацію, один інструмент і один точний набір аргументів, тому для видалення трьох агентів потрібні три підтвердження. campaign_action із pause або stop пропускає цей крок, щоб активну кампанію завжди можна було негайно зупинити; так само його пропускає test_integration із GET. Деякі інструменти D виконуються за один запит, оскільки D позначає їхній ефект, а не серверне підтвердження: update_agent замінює вміст чернетки (discard_agent_draft скасовує цю дію), deploy_agent замінює активну конфігурацію, update_phone_number перенаправляє активні дзвінки, sync_mcp_server_tools замінює каталог інструментів віддаленого сервера, import_voip_numbers перенаправляє номери на вашого оператора, run_agent_tests може витрачати кредит, send_sms і place_call зв’язуються з реальною людиною (place_call зберігає власне підтвердження згоди), а provision_phone_number купує номер. Ваш MCP-клієнт усе одно може попросити вас підтвердити ці дії.

Початкові запити

prompts/list пропонує п’ять повторно використовуваних робочих процесів:

create_inbound_receptionist
run_agent_tests
buy_and_attach_number
review_low_grade_calls
add_url_to_agent_knowledge

Використовуйте prompts/get із вказаною назвою запиту та його оголошеними аргументами, щоб отримати готове до запуску повідомлення користувача.

Ресурси

resources/list надає загальнодоступні кешовані довідкові матеріали:

URI	Вміст
`thunderphone://docs/llms.txt`	Індекс загальнодоступної документації.
`thunderphone://docs/quickstart`	Markdown для швидкого початку роботи.
`thunderphone://pricing`	Поточний Markdown із загальнодоступними цінами.

Прочитайте ресурс за допомогою resources/read. Для загальнодоступних отримань використовується короткий тайм-аут, обмеження 2 MiB і десятихвилинний кеш у процесі.

Протокол і помилки

Сервер підтримує версії протоколу 2025-06-18 і 2025-03-26; він повторює підтримувану клієнтом версію, а в інших випадках вибирає 2025-06-18. Він реалізує initialize, ping, інструменти, запити, ресурси та сповіщення. Сповіщення повертають 202 Accepted. Цей сервер без стану не надає SSE-приймача або видалення сесій, тому GET і DELETE повертають 405 Method Not Allowed із Allow: POST.

Помилки інструментів залишаються успішними відповідями JSON-RPC з isError: true. Їхній текст містить коротке речення, за яким іде блок JSON:

{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}

Для place_call зберігається окремий префікс outbound_tcpa_confirmation_required:. Невідомі методи JSON-RPC повертають -32601 у відповіді HTTP 200. Пакети JSON-RPC не підтримуються MCP 2025-06-18 і повертають чисту помилку недійсного запиту -32600.