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

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

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

Це протилежний напрямок до [підключення віддаленого MCP-сервера до голосового агента](/uk/guides/mcp-servers):

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

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

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

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

<Warning>
  Ключ `sk_live_` може читати дані організації та виконувати дії в продакшні, зокрема розгортати агентів, здійснювати дзвінки, купувати номери, запускати кампанії та видаляти ресурси. Не додавайте його в код браузера, репозиторії, знімки екрана та журнали чатів. Використовуйте сховище секретів або підтримку змінних середовища вашого клієнта й негайно відкликайте скомпрометований ключ.
</Warning>

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

[ThunderPhone CLI](/uk/guides/cli) може записувати конфігурацію клієнта, зберігаючи
непов’язані сервери:

```bash
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](/uk/guides/oauth); ключ API не потрібен. Якщо у вас ще немає облікового запису ThunderPhone, виберіть **Створити обліковий запис** на сторінці входу, і після підтвердження електронної пошти ви повернетеся на екран надання дозволів.

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

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

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

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

### ChatGPT

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

Видалення агента або номера телефону, скасування чернетки, запуск кампанії та надсилання тестового запиту, який може записувати дані до зовнішньої системи, потребують другого підтвердження в обох застосунках; див. [Підтвердження руйнівних дій](#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

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

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

### Cursor

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

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

### Claude Desktop

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

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

## Інструменти

Кожен інструмент має анотації 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 | Відкидає збережені зміни. Два кроки, див. [Підтвердження руйнівних дій](#confirming-destructive-actions). |
| `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, змінюють або видаляють щось чи починають набір номера реальних людей. Для тих, які неможливо скасувати, потрібні два запити. Перший запит нічого не змінює та повертає:

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

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