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

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

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

Claude и ChatGPT използват OAuth за влизане; не е необходим API ключ. Ако все още нямате акаунт в ThunderPhone, изберете Създаване на акаунт на страницата за влизане и след потвърждаване на имейла си ще се върнете към екрана за одобрение.

Claude (уеб, настолен компютър и мобилно устройство)

Отворете Настройки → Конектори. Ако ThunderPhone се показва в директорията с конектори, изберете го. В противен случай изберете Добавяне на персонализиран конектор, наименувайте го ThunderPhone и въведете https://api.thunderphone.com/v1/mcp.
Изберете Свързване, влезте в ThunderPhone, изберете организацията и одобрете разрешенията.
В чат активирайте 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 взаимодействие с външен свят/мрежа. Тирето означава, че няма зададен признак.

Агенти

Инструмент	Основни аргументи	Анотации	Какво прави
`list_agents`	—	R, I	Извежда списък с агенти.
`get_agent`	`agent_id`	R, I	Получава един агент.
`create_agent`	конфигурация на агент	—	Създава агент.
`update_agent`	`agent_id`, променени полета	—	Подготвя полета в черновата на агента.
`deploy_agent`	`agent_id`, незадължително `if_updated_at`	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`	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`	O	Импортира номера, които вече са притежавани при доставчика.
`update_phone_number`	`phone_number_id`, полета за маршрутизиране/етикет/уебкука	—	Актуализира маршрутизирането на номера, включително назначаването на агент.
`delete_phone_number`	`phone_number_id`, `confirm`, незадължително `release_at_provider`, `confirmation_token` при втората заявка	D, I, O	Освобождава номер. Двустъпково действие.

Обаждания

Инструмент	Основни аргументи	Анотации	Какво прави
`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`	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`, незадължителен избор/матрица	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`, незадължителни метод/заглавки/тяло/време за изчакване	O	Изпраща ограничена тестова заявка със защита срещу SSRF.
`list_webhook_endpoints`	—	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`	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	Получава баланса и официалните цени за нивата; не са предоставени промени по плащанията.
`create_agent_import`	`vendor`, `vendor_key`	O	Стартира криптирано импортиране от Vapi, Retell, ElevenLabs или Bland.
`get_agent_import`	`public_id`	R, I	Получава предложената разлика при импортиране.
`commit_agent_import`	`public_id`	—	Прилага избраните агенти от прегледан план.
`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 пропуска тази стъпка, така че изпълнявана кампания винаги може да бъде спряна веднага.

Начални подкани

prompts/list предлага шест многократно използваеми работни процеса:

create_inbound_receptionist
run_agent_tests
import_vapi_assistants
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."
}

Отличителният префикс outbound_tcpa_confirmation_required: се запазва за place_call. Непознатите JSON-RPC методи връщат -32601 в HTTP отговор 200. JSON-RPC пакетните заявки не се поддържат от MCP 2025-06-18 и връщат ясен -32600 отговор за невалидна заявка.