Wavix

Wavix MCP Server

Сервер Model Context Protocol, который предоставляет LLM и AI-агентам прямой доступ к телеком-платформе Wavix — SMS/MMS, голосовые вызовы, 2FA, SIP-транкинг, управление телефонными номерами, регистрация 10DLC, записи звонков, речевая аналитика и биллинг.

Wavix — глобальная коммуникационная платформа для отправки SMS, совершения голосовых вызовов и запуска 2FA-сценариев через единый API. Доступна бесплатная пробная версия; платное использование соответствует тарифному плану Wavix, привязанному к вашему аккаунту.

Самый быстрый способ использовать этот MCP-сервер — хостируемая конечная точка по адресу https://mcp.wavix.com/mcp — укажите на неё любой MCP-совместимый клиент и подключитесь, войдя в свой аккаунт Wavix или используя API-ключ Wavix. Если вам нужно самостоятельное размещение (собственное развёртывание Wavix, работа за брандмауэром, выделенный экземпляр), см. раздел Запустите свой собственный.

Содержание

• Конечная точка
• Установка — вход с аккаунтом, API-ключ, установка в один клик, Claude Code, Claude Desktop / Web, Cursor, VS Code, Codex CLI, Windsurf
• Запустите свой собственный (самостоятельное размещение)
• Примеры
• Инструменты → полный каталог в TOOLS.md
• Ресурсы
• Аутентификация (рекомендации, если токен скомпрометирован)
• Устранение неполадок
• Совместимость и ограничения
• Поддержка, Участие в разработке, Безопасность, Лицензия

Конечная точка

Поле	Значение
URL	https://mcp.wavix.com/mcp
Транспорт	Streamable HTTP
Аутентификация	Вход с аккаунтом Wavix (OAuth 2.1), или Authorization: Bearer <api_key>
Инструменты	см. TOOLS.md
Ресурсы	Документация Wavix + спецификация OpenAPI (автоматически обнаруживаемые)

Получите API-ключ Wavix в Консоли Wavix → Администрирование → API-ключи → Создать новый.

Установка

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

Вход с аккаунтом Wavix

Если ваш MCP-клиент поддерживает OAuth (Claude Desktop / Web и другие клиенты с поддержкой OAuth), подключитесь без API-ключа: добавьте коннектор для https://mcp.wavix.com/mcp и, когда клиент запросит, войдите в свой аккаунт Wavix и подтвердите доступ. Клиент выполнит поток OAuth 2.1 и сам сохранит токен — ничего вставлять не нужно. Доступные вам инструменты ограничены тем, что вы одобрили, и тем, что разрешает роль вашего аккаунта (см. Устранение неполадок).

Подключение с API-ключом

Перед началом: получите свой API-ключ Wavix.

1. Войдите на https://wavix.com.
2. Откройте Администрирование → API-ключи.
3. Нажмите Создать новый (или скопируйте существующий ключ). Держите его под рукой — вы вставите его вместо YOUR_API_KEY ниже.

Установка в один клик

⚠️ Кнопки ниже заполняют конфигурацию MCP вашего редактора плейсхолдером YOUR_API_KEY. После завершения установки редактором откройте сгенерированную конфигурацию и замените плейсхолдер на ваш реальный API-ключ перед отправкой любого запроса — иначе каждый вызов будет возвращать 401 Unauthorized.

Чтобы удалить позже: откройте тот же файл конфигурации (~/.cursor/mcp.json, .vscode/mcp.json или эквивалентный для вашего редактора) и удалите запись wavix, или удалите коннектор через интерфейс MCP / Connectors вашего редактора.

Claude Code

claude mcp add --transport http wavix https://mcp.wavix.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Используйте claude mcp list для проверки и /mcp внутри сессии для получения статуса.

Claude Desktop / Claude Web

Настройки → Connectors → Add custom connector:

• Имя: Wavix
• URL: https://mcp.wavix.com/mcp
• Транспорт: Streamable HTTP
• Заголовок аутентификации: Authorization: Bearer <api_key>

Чтобы подключиться через вход в систему вместо этого, добавьте коннектор без заголовка аутентификации и войдите в свой аккаунт Wavix, когда клиент запросит.

Cursor (вручную)

Добавьте в ~/.cursor/mcp.json (или в проектный .cursor/mcp.json):

{
  "mcpServers": {
    "wavix": {
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

Cursor 2.4+ отображает полный каталог; более ранние версии ограничены 40 инструментами.

VS Code (вручную, GitHub Copilot Chat)

Создайте .vscode/mcp.json в вашем рабочем пространстве (или добавьте тот же объект servers под ключом "mcp" в пользовательском settings.json):

{
  "servers": {
    "wavix": {
      "type": "http",
      "url": "https://mcp.wavix.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}

См. руководство по MCP-серверам VS Code для актуальной схемы.

Codex CLI

Codex CLI поддерживает MCP через stdio. Подключитесь к хостируемому серверу через mcp-remote. Отредактируйте ~/.codex/config.toml:

[mcp_servers.wavix]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://mcp.wavix.com/mcp",
  "--header",
  "Authorization:Bearer ${WAVIX_API_KEY}"
]

[mcp_servers.wavix.env]
WAVIX_API_KEY = "YOUR_API_KEY"

Windsurf / другие клиенты

Любой MCP-клиент, поддерживающий транспорт Streamable HTTP с пользовательскими заголовками, будет работать. Используйте:

• URL: https://mcp.wavix.com/mcp
• Заголовок: Authorization: Bearer <api_key>

Настраиваете через AI-агента? Укажите вашему агенту на llms-install.md — это машиночитаемое руководство по установке, которое предоставляет модели URL, заголовок и конфигурацию для каждого клиента в детерминированном формате, чтобы она не импровизировала значения конечных точек.

Запустите свой собственный

Хостируемый сервер работает из коробки для большинства пользователей. Самостоятельное размещение необходимо, если вы хотите указать на непубличное развёртывание Wavix, работать за брандмауэром или действовать в рамках собственной инфраструктуры.

Docker

docker build -t wavix-mcp-server .
docker run --rm -p 8000:8000 wavix-mcp-server

Сервер прослушивает порт 8000 и предоставляет MCP-конечную точку по адресу /mcp. Укажите вашему клиенту на http://<host>:8000/mcp.

Из исходного кода

git clone https://github.com/Wavix/wavix-mcp-server.git
cd wavix-mcp-server
pip install -e .
wavix-mcp

Требуется Python 3.10+.

Конфигурация

Переменная окружения	По умолчанию	Назначение
WAVIX_API_BASE_URL	https://api.wavix.com	Переопределить вышестоящую конечную точку API Wavix (для внутренних развёртываний или staging)
OAUTH_ISSUER	не задано	Базовый URL сервера авторизации OAuth 2.1. Его JWKS читается из <issuer>/.well-known/jwks.json
OAUTH_RESOURCE	не задано	Публичный базовый URL, по которому доступен этот сервер, используется как идентификатор ресурса
OAUTH_API_KEY_PASSTHROUGH	true	При включённом OAuth по-прежнему принимать bearer-токен, не являющийся OAuth JWT, и передавать его вышестоящему серверу (API-ключи продолжают работать). Установите false, чтобы требовать JWT
MCP_PATH	/mcp	Путь, по которому обслуживается MCP-конечная точка

Для запуска сервера не требуются учётные данные Wavix — они передаются в каждом запросе из заголовка Authorization: Bearer <api_key> MCP-клиента. Самостоятельно размещающие пользователи отвечают за завершение TLS перед сервером (nginx, Caddy, облачный балансировщик нагрузки) перед публичным доступом.

OAuth 2.1 (опционально)

Установите OAUTH_ISSUER и OAUTH_RESOURCE вместе, чтобы превратить сервер в защищённый ресурс OAuth 2.1. Затем он публикует метаданные RFC 9728 по адресу /.well-known/oauth-protected-resource<MCP_PATH>, проверяет входящие токены доступа как JWT против JWKS эмитента и отвечает на неаутентифицированные запросы вызовом WWW-Authenticate, указывающим на эти метаданные. MCP-клиенты, поддерживающие OAuth, используют это для самостоятельного выполнения потока авторизации, поэтому пользователям больше не нужно вставлять API-ключ в конфигурацию клиента.

Аудитория, которую должен нести каждый токен, — это OAUTH_RESOURCE + MCP_PATH, что также является значением resource, публикуемым в метаданных. Серверы авторизации, реализующие RFC 8707, сравнивают параметр resource клиента с этой строкой точно, поэтому они должны быть настроены на совпадение — включая путь.

Включение OAuth не отключает клиентов, которые аутентифицируются с помощью API-ключа Wavix. Bearer-токен, не являющийся действительным OAuth JWT, передаётся вышестоящему серверу без проверки, как и раньше, оставляя API Wavix единственным авторитетом в этом вопросе — поэтому существующее развёртывание может включить OAuth для новых клиентов, не нарушая работу уже подключённых. Запрос без токена по-прежнему получает вызов WWW-Authenticate, что позволяет OAuth-совместимому клиенту обнаружить сервер авторизации. Только OAuth-аутентифицированные подключения фильтруются по областям; подключение через API-ключ видит полную поверхность инструментов.

Установите OAUTH_API_KEY_PASSTHROUGH=false, чтобы отключить этот запасной вариант и требовать действительный JWT — строгий режим, на который следует переключиться после прекращения доступа через API-ключи.

Если оставить любую из переменных OAUTH_ISSUER / OAUTH_RESOURCE незаданной, сохраняется прежнее поведение: метаданные не публикуются, и любой bearer-токен, отправленный клиентом, передаётся вышестоящему серверу без проверки.

Примеры

Конкретные промпты, которые можно использовать в любом подключённом клиенте.

Номера телефонов ниже (+1 310 555 0100, +44 7700 900123) находятся в зарезервированных тестовых диапазонах (NANP 555 и Ofcom 070 09xx) — их можно безопасно копировать дословно, через них недоступны реальные абоненты.

Отправка транзакционного SMS

Промпт: "Отправь SMS с +13105550100 на +447700900123 с текстом 'Ваш код подтверждения: 4821'."

Агент вызывает sms_and_mms_messages_send с from, to и text. Возвращается идентификатор сообщения и статус доставки.

Запуск 2FA-проверки

Промпт: "Отправь 2FA-код подтверждения на +13105550100 через SMS. Когда я дам тебе полученный код, проверь, правильный ли он."

Агент вызывает two_fa_verification_create, ждёт, пока вы поделитесь кодом, полученным по SMS, затем вызывает two_fa_verification_check. Полезно для прототипирования сценариев без пароля без написания интеграционного кода.

Поиск и покупка телефонного номера

Промпт: "Найди доступный бесплатный номер США с поддержкой SMS, добавь его в корзину и оформи заказ."

Агент последовательно вызывает buy_numbers_list (с фильтрацией по стране и функциям), cart_add и cart_checkout. cart_checkout сначала возвращает предварительный просмотр с номерами и их комиссиями, и списывает средства с аккаунта только при повторном вызове с его confirmation_token.

Поиск по транскрипциям звонков

Промпт: "Покажи все входящие звонки со вчерашнего дня длиннее двух минут, где звонящий упомянул 'возврат'."

Агент использует cdrs_search для поиска по транскрипциям, затем обогащает каждый результат через cdrs_get для получения полных метаданных звонка.

Получение записи и её транскрибация

Промпт: "Получи запись звонка abc-123, попроси Wavix транскрибировать её и верни транскрипцию."

Агент вызывает call_recording_get_by_call (возвращает предварительно подписанный URL для скачивания), cdrs_retranscribe, затем опрашивает cdrs_transcription_get.

Аудит биллинга

Промпт: "Сколько мы потратили на SMS в прошлом месяце и какие счета были выставлены?"

Агент вызывает billing_transactions_list с фильтрацией по типу и дате, затем billing_invoices_list. Скачивание самого PDF-счёта не доступно через MCP — получите его через API Wavix или панель управления.

Инструменты

Сгенерировано из спецификации OpenAPI Wavix. Аргументы отражают параметры запросов и поля тела. Отображаемые инструменты зависят от разрешений, которые вы одобряете при входе, и функций, включённых в вашем аккаунте.

Группа	Покрытие
SMS и MMS	Отправка, список, получение сообщений; идентификаторы отправителей; отписки
WhatsApp	Бизнес-аккаунты; отправители; шаблоны; отправка / список / получение сообщений
Управление звонками	Начало / ответ / завершение звонков; воспроизведение аудио; сбор DTMF
Запись звонков	Список, загрузка (предварительно подписанный URL), удаление
Стриминг звонков	Запуск / остановка медиапотока
Вебхуки звонков	Список, создание, удаление
CDR	Список, получение; поиск по транскрипциям и повторная транскрипция
Речевая аналитика	Транскрибация, получение исходного файла
2FA	Создание / проверка / отмена / повторная отправка верификации; события
Мои номера	Список, обновление, освобождение; маршрутизация SMS / голоса
Покупка	Страны, регионы, города; поиск доступных номеров
Корзина	Добавление, удаление, получение, оформление заказа
Валидатор номеров	Одиночная и массовая валидация
SIP-транки	Полный CRUD
10DLC	Бренды, кампании, верификация, доказательства, подписки на события
Профиль	Получение / обновление профиля; конфигурация аккаунта
API-ключи	Список, создание, обновление, удаление
Субаккаунты	Список, создание, получение, обновление; транзакции
Биллинг	Транзакции; список счетов / выписок
Голосовые кампании	Запуск и получение
Wavix Embeddable (WebRTC)	CRUD токенов виджетов
Сокращатель ссылок	Создание коротких ссылок; метрики

См. TOOLS.md для полного списка инструментов с однострочными описаниями. Авторитетным источником является спецификация Wavix OpenAPI — ваш клиент всегда видит актуальный живой каталог.

Ресурсы

В дополнение к инструментам сервер предоставляет документацию Wavix в виде MCP ресурсов, чтобы модель могла получать авторитетный контекст по запросу, а не полагаться на предыдущие знания.

Схема URI	Содержимое
wavix://docs/<path>	Страницы документации с docs.wavix.com (автоматически обнаруживаются через llms.txt).
wavix://api/openapi.yaml	Полная спецификация Wavix OpenAPI 3.0.

Оба источника — docs.wavix.com и спецификация Wavix OpenAPI — публично доступны и могут просматриваться напрямую без аутентификации.

Ресурсы загружаются лениво при resources/read и кэшируются на стороне сервера с TTL 1 час. Передаваемый Bearer-токен никогда не пересылается на хостинги документации — только на api.wavix.com.

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

Размещённый сервер принимает два способа подключения — ни один не является предпочтительным:

• Вход с аккаунтом Wavix (OAuth 2.1). Для клиентов, поддерживающих OAuth. Клиент запускает процесс авторизации, и пользователь входит в систему; API-ключ не сохраняется. Доступ ограничен областями, которые одобрил пользователь, и разрешениями его роли в аккаунте. См. Вход с аккаунтом Wavix.
• API-ключ Wavix (Bearer). Для любого клиента Streamable-HTTP. Каждый запрос должен включать:

Authorization: Bearer <api_key>

Сервер пересылает этот заголовок на api.wavix.com для каждого запроса. Токен:

• никогда не логируется,
• никогда не пересылается при кросс-хостовых редиректах (например, предварительно подписанные URL загрузки S3),
• никогда не отправляется на хостинги документации.

Если ваш клиент переходит по предварительно подписанному URL загрузки, возвращённому call_recording_get_by_call, speech_analytics_file_get или ten_dlc_brand_evidence_get, загружайте его напрямую без заголовка Authorization.

Рекомендации

• Используйте выделенный API-ключ для MCP. Создайте отдельный API-ключ в https://wavix.com → Администрирование → API-ключи (или через сам инструмент api_keys_create из другой сессии). Это позволит отозвать доступ MCP без нарушения других интеграций.

• Периодически ротируйте. Относитесь к API-ключу как к любому производственному секрету: ротируйте по расписанию и при любом подозрении на утечку.

• Не храните API-ключи в git. Конфигурации MCP-клиентов легко случайно закоммитить, утащив токен в историю и логи CI. Большинство клиентов поддерживают подстановку ${env:VAR} в значении заголовка — храните API-ключ в переменной окружения или в связке ключей ОС и ссылайтесь на него из конфигурации. В качестве страховки добавьте общие пути конфигураций клиентов в ваш .gitignore:

  .cursor/mcp.json
  .vscode/mcp.json
  claude_desktop_config.json
  .claude/mcp.json
  .codex/config.toml
  

Если учётные данные скомпрометированы

Если вы подключились с API-ключом:

1. В консоли Wavix немедленно деактивируйте или удалите этот ключ (или вызовите api_keys_delete).
2. Создайте замену через api_keys_create или консоль.
3. Обновите конфигурацию клиента и переподключитесь.

Если вы подключились через вход в аккаунт Wavix:

1. Отзовите подключение на странице управления разрешениями портала Wavix, где перечислены авторизованные вами подключения, и отзовите нужное — это аннулирует токены этого подключения. API-ключ не задействован.
2. Переподключитесь и войдите снова.

В любом случае проверьте billing_transactions_list и cdrs_list на предмет неожиданной активности.

Устранение неполадок

Симптом	Вероятная причина / решение
401 Unauthorized от любого инструмента	Ошибка аутентификации. С API-ключом: заголовок Authorization: Bearer … отсутствует, или ключ недействителен или неактивен — проверьте его в консоли Wavix. При входе в аккаунт: ваша сессия/токен истёк или был отозван, или вход не был завершён — переподключитесь и войдите снова.
Инструмент возвращает download_url, а не сам файл	Ожидаемо. Конечные точки записей, речевой аналитики и доказательств 10DLC возвращают предварительно подписанные URL (см. Аутентификация). Загружайте URL напрямую без заголовка Authorization.
Клиент показывает только часть каталога	Старые клиенты применяют ограничение на количество инструментов на сервер. Обновитесь (Cursor 2.4+, последний VS Code, последний Claude).
Меньше инструментов после входа в аккаунт Wavix	Ожидаемо. Вход в аккаунт фильтруется по областям — вы получаете инструменты, разрешённые одобренными областями и ролью аккаунта, а не полный каталог. Подключение с API-ключом видит всю поверхность инструментов. Чтобы расширить набор, одобрите больше областей при входе (в зависимости от роли) или подключитесь с API-ключом, который их содержит.
Tool not found для инструмента, указанного в этом README	Локальный клиент может кэшировать старый список инструментов. Перезапустите клиент или удалите и добавьте сервер заново.
4xx с массивом errors	Ошибка валидации от API Wavix. Изучите errors; сверьтесь с соответствующей страницей wavix://docs/* или спецификацией OpenAPI.
Невозможно подключиться к серверу	Проверьте DNS и исходящий HTTPS до mcp.wavix.com:443.
Агент неожиданно вызывает деструктивный инструмент	Большинство клиентов могут требовать подтверждения перед вызовами инструментов — включите эту настройку и перейдите на выделенный MCP API-ключ (см. Рекомендации).

Совместимость и ограничения

• Совместим с любым MCP-клиентом, поддерживающим транспорт Streamable HTTP (Claude Desktop / Web / Code, Cursor 2.4+, VS Code, Windsurf, пользовательские MCP SDK) и любой агентный фреймворк с MCP-адаптером клиента.
• Каждый инструмент, аннотированный destructiveHint, а также call_webhooks_create, sip_trunks_update и sub_accounts_update, работает в два шага: первый вызов возвращает предпросмотр и одноразовый confirmation_token (действителен 5 минут), а действие выполняется только при повторном вызове инструмента с теми же аргументами и этим токеном. Любой MCP-клиент может это сделать; поддержка подтверждения на стороне клиента не требуется.
• Старые клиенты могут применять ограничение на количество инструментов на сервер; обновитесь до последней версии для доступа к полному каталогу.
• Лимиты скорости и плата за использование соответствуют вашему тарифному плану аккаунта Wavix. См. Цены Wavix.

Журнал изменений

Размещённый сервер обновляется непрерывно по мере развития спецификации Wavix OpenAPI; новые инструменты появляются автоматически, а аргументы существующих инструментов могут получать дополнительные необязательные поля. Изменения документации этого репозитория отслеживаются в Releases. При существенных изменениях поведения, затрагивающих входные данные инструментов или аутентификацию, мы публикуем уведомление и там, и в примечаниях к выпускам Wavix.

Поддержка

• Документация продукта: https://docs.wavix.com
• Справочник API: https://docs.wavix.com/api-reference
• Вопросы / обратная связь: support@wavix.com

Участие в разработке

Этот репозиторий доступен в исходном виде, но не открыт для внешних contributions. Pull request'ы автоматически закрываются, а Issues / Discussions отключены. Отправляйте отчёты об ошибках, запросы функций и обратную связь на support@wavix.com. См. CONTRIBUTING.md для подробностей.

Если вы нашли ошибку в базовом фреймворке FastMCP, сообщите о ней выше по течению.

Безопасность

Чтобы сообщить об уязвимости безопасности, отправьте email на support@wavix.com с темой Security: <short summary> вместо открытия публичного issue. См. SECURITY.md для подробностей.

Лицензия

MIT © Wavix