Используйте ThunderPhone как MCP-сервер

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

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

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

Это противоположное направление по сравнению с подключением удалённого MCP-сервера к голосовому агенту:

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

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

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

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

CLI ThunderPhone может записывать конфигурацию клиента, сохраняя несвязанные серверы:

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, выберите Создать аккаунт на странице входа — после подтверждения 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 в чат через меню инструментов.

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

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 — взаимодействие с внешним миром или сетью. Тире означает, что подсказка не задана.

Подключение#

Агенты#

Номера телефонов и операторы#

SMS#

Звонки#

Тестирование и проверка#

База знаний#

Интеграции, вебхуки и удалённые серверы MCP#

Кампании#

Голоса, биллинг и документация#

Все инструменты продукта используют те же пути 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 минут и распространяется на одну организацию, один инструмент и один точный набор аргументов, поэтому для удаления 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 предоставляет общедоступные кэшированные ссылки:

Прочитайте ресурс с помощью 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."
}

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