---
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 сървър с гласов агент](/bg/guides/mcp-servers):

| Посока | Резултат |
| --- | --- |
| Отдалечен MCP сървър → агент на ThunderPhone | Гласов агент може да извиква инструментите на отдалечения сървър. |
| ThunderPhone → вашият MCP клиент | Вашият агент за програмиране може да изгражда, тества и управлява ThunderPhone. |

## Удостоверяване

Използвайте [OAuth](/bg/guides/oauth) по подразбиране за клиенти за директории: влезте, изберете организация и одобрете заявените разрешения. Отменете достъпа от **Организация → API ключове → Оторизирани приложения**.

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

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

## CLI и алтернативи със stdio

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

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

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

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

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

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

### Агенти

| Инструмент | Основни аргументи | Анотации | Какво прави |
| --- | --- | --- | --- |
| `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 | Отхвърля подготвените промени. Двустъпково действие, вижте [Потвърждаване на разрушителни действия](#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` | 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, променят или премахват нещо, което не може да бъде възстановено, или започват набиране на реални хора. Те изискват две заявки. Първата заявка не променя нищо и връща:

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

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

`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 блок:

```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` отговор за невалидна заявка.