MCP: подключить WAIX к ИИ-ассистенту

01Доступ и лимиты

Для вызова инструментов MCP нужен действующий пробный доступ WAIX или оплаченный тариф. Во время пробных 24 часов применяются лимиты «Старта» для одного номера. После окончания пробного доступа инструменты перестанут выполняться до оплаты тарифа; сам факт подключения ассистента не продлевает доступ.

У каждого тарифа есть три ограничения MCP: число активных подключений ассистентов, вызовы инструментов за период и запросы в минуту. Они общие для всех сотрудников и подключений компании. Текущий расход показан в разделе MCP и в подписке.

Учитывается каждый допущенный вызов инструмента, в том числе завершившийся ошибкой. Новый вызов после ошибки расходует ещё один. Инициализация протокола, получение списков и чтение документации как MCP-ресурса не требуют оплаченного периода и не расходуют лимит вызовов инструментов; ограничение частоты запросов сохраняется. Поиск документации через инструмент — это вызов инструмента, для него нужен действующий доступ.

Квота оплаченного тарифа обновляется с началом следующего периода и не переносится. При исчерпании возвращается PLAN_LIMIT_EXCEEDED; превышение лимита автоматически не оплачивается. Если достигнут лимит подключений, отзовите ненужное в разделе MCP. Подготовка сообщений может быть отключена условиями тарифа. Реальную отправку всегда подтверждает человек в кабинете WAIX.

02Что можно поручить ассистенту

MCP связывает ИИ-приложение с WAIX. Ассистент может найти инструкцию, показать подключённые номера, прочитать шаблоны и проверить статус сообщения. Например: «Почему сообщение с этим ID не доставлено?» или «Найди инструкцию по 24-часовому окну». Он получает данные только текущей компании.

03Подключение в Cursor

В настройках MCP добавьте удалённый сервер по адресу https://waix.kz/api/v1/mcp. Если вы редактируете конфигурацию вручную, добавьте запись ниже в .cursor/mcp.json проекта или ~/.cursor/mcp.json. Сервер использует Streamable HTTP.

{
  "mcpServers": {
    "waix": { "url": "https://waix.kz/api/v1/mcp" }
  }
}

Приложение откроет вход в WAIX. Войдите, проверьте компанию, название приложения и адрес возврата. Выберите права и подтвердите доступ. Для других клиентов нужен удалённый MCP с OAuth, PKCE S256 и динамической регистрацией приложений. Совместимость зависит от клиента; одного поля для статического API-ключа недостаточно.

04Права и срок доступа

Подключение доступно владельцу, администратору и разработчику. Чтение документации, номеров, шаблонов и статусов входит в mcp:read. mcp:send разрешает готовить сообщения. mcp:otp включает тесты OTP в выбранном Sandbox-проекте. При подключении можно снять необязательные права.

Доступ выдаётся на 90 дней. Токен доступа живёт 15 минут; клиент обновляет его с помощью refresh token, который меняется при каждом обновлении и действует до 30 дней без использования, в пределах срока подключения. В разделе «MCP» можно отозвать доступ. Владелец и администратор видят подключения всей компании; разработчик — свои. Выход из кабинета не отключает приложение: для этого отзовите доступ.

05Отправка: сначала текст, затем подтверждение

Попросите ассистента подготовить сообщение, укажите Connection ID, получателя, имя и язык одобренного шаблона, значения переменных. Инструмент waix_prepare_template_message вернёт предварительный просмотр и ссылку на WAIX. На этом шаге сообщение не отправляется.

Откройте ссылку и проверьте номер, язык и полный текст. После вашего подтверждения WAIX поставит одно сообщение в очередь. Ссылка действует 10 минут, подтвердить её может только пользователь, подключивший приложение, в той же компании. Подтверждение в чате с ассистентом не заменяет нажатие кнопки в WAIX.

Поддерживаются текстовые шаблоны без медиа и кнопок, с числовыми переменными {{1}}, {{2}}. Шаблоны авторизации, именованные переменные и другие типы отправляйте через обычный API или кабинет. Если шаблон изменился, потребуется подготовить новую заявку.

Сохраняются проверки действующего доступа WAIX, номера и шаблона. Пробный доступ не включает оплату сообщений Meta. Повторное подтверждение одной заявки не создаёт вторую отправку. Статус заявки sent означает постановку в очередь; доставку проверяйте через waix_message_status или журнал сообщений. Отзыв доступа не отменяет сообщения, уже принятые в очередь.

06OTP только для разработки

При подключении выберите право mcp:otp и активный Sandbox-проект. Если его ещё нет, создайте проект в разделе OTP. Инструменты позволяют создать тестовый код, проверить его и узнать статус. Сообщение в WhatsApp не отправляется, квота платного пакета не расходуется.

Для waix_otp_sandbox_send передавайте UUID в idempotency_key: один UUID для одного запроса, тот же при повторе. test_code предназначен для локальных тестов. Через MCP нельзя отправить рабочий код, получить чужой OTP или авторизовать реального пользователя. Перевод проекта в Live прекращает действие этого MCP-подключения.

07Инструменты

08Что делать при ошибке

Если пробный доступ или подписка закончились, откройте «Подписка» и выберите тариф. Не переподключайте ассистента ради продления: доступ к инструментам проверяется на каждый вызов.

401 — доступ отозван, истёк или изменились права пользователя: подключите приложение заново. Нет инструмента отправки — при подключении не выдано mcp:send. Нет OTP-инструментов — не выдано mcp:otp. Чтобы добавить права, отзовите прежнее подключение и создайте новое.

429 — слишком много запросов. Сервер допускает до 120 MCP-запросов в минуту на подключение; дополнительно действуют ограничения API и OTP. Дождитесь Retry-After. Если отправка прервалась, откройте ту же заявку и обновите статус. При необходимости повторите её подтверждение спустя минуту, не создавая новую.

Если кабинет показывает другую компанию, переключите её и заново откройте ссылку подтверждения. При технической ошибке передайте поддержке request_id, без токенов и кодов авторизации.

09Для разработчиков MCP-клиентов

Адрес ресурса — https://waix.kz/api/v1/mcp. Metadata доступна по /.well-known/oauth-protected-resource/api/v1/mcp, OAuth discovery — по /.well-known/oauth-authorization-server. Сервер принимает POST JSON-RPC, не хранит транспортные сессии и не открывает фоновый SSE-поток. Используется стабильный SDK с протоколом 2025-11-25 и согласованием поддерживаемой версии.

OAuth: authorization code, обязательный PKCE S256, public client с token_endpoint_auth_method=none. Передавайте resource с точным адресом MCP при авторизации и обмене токена. Redirect URI должен совпадать с зарегистрированным; HTTP допустим только для localhost/loopback. Повторное использование уже обменённого refresh token отзывает всё подключение.

Bearer-токены MCP предназначены только для MCP. Обычный ключ WAIX API здесь не принимается. Секреты Meta, реквизиты оплаты, содержимое переписки и рабочие OTP-коды не включаются в ответы инструментов. Документация также доступна как resources с URI waix://docs/{slug}.