MCP: подключить WAIX к ИИ-ассистенту
Подключение по URL, выбор прав, проверка номеров и шаблонов, подтверждение отправки и OTP в Sandbox.
Что можно поручить ассистенту
MCP связывает ИИ-приложение с WAIX. Ассистент может найти инструкцию, показать подключённые номера, прочитать шаблоны и проверить статус сообщения. Например: «Почему сообщение с этим ID не доставлено?» или «Найди инструкцию по 24-часовому окну». Он получает данные только текущей компании.
Подключение в 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-ключа недостаточно.
Права и срок доступа
Подключение доступно владельцу, администратору и разработчику. Чтение документации, номеров, шаблонов и статусов входит в mcp:read. mcp:send разрешает готовить сообщения. mcp:otp включает тесты OTP в выбранном Sandbox-проекте. При подключении можно снять необязательные права.
Доступ выдаётся на 90 дней. Токен доступа живёт 15 минут; клиент обновляет его с помощью refresh token, который меняется при каждом обновлении и действует до 30 дней без использования, в пределах срока подключения. В разделе «MCP» можно отозвать доступ. Владелец и администратор видят подключения всей компании; разработчик — свои. Выход из кабинета не отключает приложение: для этого отзовите доступ.
Отправка: сначала текст, затем подтверждение
Попросите ассистента подготовить сообщение, укажите Connection ID, получателя, имя и язык одобренного шаблона, значения переменных. Инструмент waix_prepare_template_message вернёт предварительный просмотр и ссылку на WAIX. На этом шаге сообщение не отправляется.
Откройте ссылку и проверьте номер, язык и полный текст. После вашего подтверждения WAIX поставит одно сообщение в очередь. Ссылка действует 10 минут, подтвердить её может только пользователь, подключивший приложение, в той же компании. Подтверждение в чате с ассистентом не заменяет нажатие кнопки в WAIX.
Поддерживаются текстовые шаблоны без медиа и кнопок, с числовыми переменными {{1}}, {{2}}. Шаблоны авторизации, именованные переменные и другие типы отправляйте через обычный API или кабинет. Если шаблон изменился, потребуется подготовить новую заявку.
Сохраняются проверки подписки, доступности номера и шаблона. Применяются обычные тарифы WAIX и Meta. Повторное подтверждение одной заявки не создаёт вторую отправку. Статус заявки sent означает постановку в очередь; доставку проверяйте через waix_message_status или журнал сообщений. Отзыв доступа не отменяет сообщения, уже принятые в очередь.
OTP только для разработки
При подключении выберите право mcp:otp и активный Sandbox-проект. Если его ещё нет, создайте проект в разделе OTP. Инструменты позволяют создать тестовый код, проверить его и узнать статус. Сообщение в WhatsApp не отправляется, квота платного пакета не расходуется.
Для waix_otp_sandbox_send передавайте UUID в idempotency_key: один UUID для одного запроса, тот же при повторе. test_code предназначен для локальных тестов. Через MCP нельзя отправить рабочий код, получить чужой OTP или авторизовать реального пользователя. Перевод проекта в Live прекращает действие этого MCP-подключения.
Инструменты
| Инструмент | Действие |
|---|---|
| waix_search_docs | Поиск по публичной документации |
| waix_read_docs | Текст статьи по slug |
| waix_list_connections | Номера и состояние подключения |
| waix_list_templates | До 200 шаблонов выбранного номера |
| waix_message_status | Статус сообщения и коды ошибок без тела переписки |
| waix_prepare_template_message | Подготовка одного сообщения |
| waix_action_status | Статус заявки на отправку |
| waix_otp_sandbox_send | Тестовый код без отправки |
| waix_otp_sandbox_verify | Проверка тестового кода |
| waix_otp_sandbox_status | Состояние тестового запроса |
Что делать при ошибке
401 — доступ отозван, истёк или изменились права пользователя: подключите приложение заново. Нет инструмента отправки — при подключении не выдано mcp:send. Нет OTP-инструментов — не выдано mcp:otp. Чтобы добавить права, отзовите прежнее подключение и создайте новое.
429 — слишком много запросов. Сервер допускает до 120 MCP-запросов в минуту на подключение; дополнительно действуют ограничения API и OTP. Дождитесь Retry-After. Если отправка прервалась, откройте ту же заявку и обновите статус. При необходимости повторите её подтверждение спустя минуту, не создавая новую.
Если кабинет показывает другую компанию, переключите её и заново откройте ссылку подтверждения. При технической ошибке передайте поддержке request_id, без токенов и кодов авторизации.
Для разработчиков 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}.