Използвайте ThunderPhone като MCP сървър

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

ThunderPhone предоставя 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 изискват съответното внедряване на API OAuth. Пътят с API ключ не го изисква. Директните HTTP конфигурации не четат хранилището за идентификационни данни на CLI; използвайте обвивката stdio, за да използвате повторно влизането от устройство.

Това са алтернативи на ръчните конфигурации на клиенти по-долу.

Конфигуриране на клиента#

Claude и ChatGPT влизат чрез 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 към чат от менюто с инструменти.

Изтриването на агент или телефонен номер, отхвърлянето на чернова, стартирането на кампания и изпращането на тестова заявка, която може да записва във външна система, изискват второ потвърждение и в двете приложения; вижте Потвърждаване на разрушителни действия.

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 минути и важи за една организация, един инструмент и един точен набор от аргументи, така че изтриването на три агента изисква три потвърждения. 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.