---
title: "Используйте ThunderPhone как MCP-сервер"
description: "Создавайте, тестируйте, проверяйте и эксплуатируйте голосовых агентов ThunderPhone из Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code или другого клиента Streamable HTTP MCP."
---

ThunderPhone предоставляет сервер Model Context Protocol с потоковой передачей по HTTP по адресу:

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

Это противоположное направление по сравнению с [подключением удалённого MCP-сервера к голосовому агенту](/ru/guides/mcp-servers):

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

## Аутентификация

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

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

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

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

[CLI ThunderPhone](/ru/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](/ru/guides/oauth); ключ API не требуется. Если у вас ещё нет аккаунта ThunderPhone, выберите **Создать аккаунт** на странице входа — после подтверждения email вы вернётесь на экран одобрения.

### 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 | Отменяет сохранённые изменения. Выполняется в 2 этапа, см. [Подтверждение деструктивных действий](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, необязательный `name` | — | Копирует агента внутри организации. |
| `delete_agent` | `agent_id`, `confirmation_token` во втором запросе | D, I | Безвозвратно удаляет агента. Выполняется в 2 этапа. |
| `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 | Освобождает номер. Выполняется в 2 этапа. |

### 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 минут и распространяется на одну организацию, один инструмент и один точный набор аргументов, поэтому для удаления 3 агентов потребуется 3 подтверждения. `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."
}
```

Отдельный префикс `outbound_tcpa_confirmation_required:` сохраняется для `place_call`. Неизвестные методы JSON-RPC возвращают `-32601` в ответе HTTP `200`. Пакеты JSON-RPC не поддерживаются MCP `2025-06-18` и возвращают корректную ошибку недопустимого запроса `-32600`.