MCP-сервер AW BI¶
MCP-сервер AW BI позволяет подключить внешнего ИИ-агента к данным Системы. Пользователь задает вопрос на естественном языке, а агент получает данные через виджеты и использует их для анализа. Для подключения необходим клиент с поддержкой MCP.
Виджеты определяют структуру данных, доступных агенту. Агент может запрашивать данные с необходимыми условиями фильтрации и выполнять анализ без изменения самого виджета. При получении данных применяются права доступа пользователя и правила доступа на уровне строк (RLS).
Как начать работу¶
Для работы необходимы учетная запись AW BI с доступом к нужным данным, API-ключ с областью применения MCP и клиент с поддержкой MCP.
1. Подготовьте доступ в AW BI¶
Выберите учетную запись, от имени которой будет работать ИИ-агент. Рекомендуется использовать отдельную учетную запись, чтобы управлять доступом агента независимо от прав основного пользователя.
Убедитесь, что для выбранной учетной записи:
- разрешены создание и использование API-ключей. Если они недоступны, обратитесь к техническому администратору. Он должен включить API-ключи в Центре управления → API-ключи → Настройки доступа и при необходимости предоставить доступ пользователю. Подробнее — Настройки доступа к API-ключам;
- предоставлено как минимум право Просмотр на каждый виджет, данные которого нужны для анализа. Для работы с информационной панелью необходим доступ к панели и к ее виджетам. При отсутствии прав обратитесь к владельцу объектов. Подробнее — Общий доступ к виджетам.
Размещение виджета на доступной пользователю информационной панели не предоставляет агенту доступ к самому виджету. Если право просмотра виджета отсутствует, агент не сможет получить его данные через MCP, даже если пользователь видит их при просмотре панели.
2. Создайте API-ключ¶
Войдите в AW BI под выбранной учетной записью и откройте Личный кабинет → Ключи API.
- Нажмите Добавить.
- Укажите Наименование и Срок действия ключа.
- В поле Область применения установите флажок MCP.
- Нажмите Создать.
- В открывшемся окне нажмите Копировать и сохраните токен — он понадобится на следующем шаге.
Полный токен доступен только при создании ключа. После закрытия окна повторно получить его нельзя; при утрате токена необходимо создать новый ключ.
Подробное описание со скриншотами — Создание ключа.
3. Подключите MCP-клиент¶
Адрес MCP-сервера формируется добавлением /mcp к адресу AW BI. Например, если Система доступна по адресу https://aw-demo.ru, адрес сервера — https://aw-demo.ru/mcp. Для проверки подключения необходимо использовать MCP-клиент.
- Откройте настройки подключения MCP-серверов в используемом клиенте.
- Добавьте сервер и укажите его адрес.
- Настройте аутентификацию с помощью токена, сохраненного на шаге 2.
- Сохраните настройки и подключитесь к серверу.
Названия элементов настройки и способ указания токена зависят от используемого клиента.
4. Проверьте подключение¶
В MCP-клиенте проверьте, что сервер подключен и его инструменты доступны. После этого можно отправить первый запрос к данным.
Если подключение не установлено, проверьте адрес сервера и токен. Убедитесь, что владельцу разрешено использование API-ключей, данный API-ключ активен, срок его действия не истек и выбрана область применения MCP. Управление ключами описано в разделе Ключи API.
5. Отправьте запрос к данным¶
В чате клиента укажите MCP-сервер AW BI, нужный виджет или информационную панель, показатели и условия анализа. Например:
Используй виджет «Продажи». Сравни выручку по регионам за первый и второй кварталы 2026 года. Учитывай только завершенные заказы. Покажи значения за каждый квартал и изменение в процентах.
Замените название виджета, показатели и условия фильтрации на соответствующие вашей задаче. Если агенту недоступен нужный виджет, проверьте права выбранной учетной записи на этот виджет, как описано в шаге 1.
Состояние интерфейса панели, включая пользовательские фильтры, закладки и связи виджетов, автоматически не переносится в запросы агента через MCP. Укажите нужный период, значения фильтров и условия анализа в запросе. Если условия отбора данных различаются, результат анализа может отличаться от значений на панели.
Пример подключения в Codex
Пример показывает подключение Codex в Windows с передачей токена через переменную окружения пользователя. Можно выбрать другой MCP-клиент или поддерживаемый им способ передачи токена.
1. Сохраните токен
Выполните команду в PowerShell или командной строке Windows. Вместо API_TOKEN подставьте токен, скопированный при создании API-ключа с областью применения MCP:
Токен сохранится в переменной AW_BI_MCP_TOKEN. Ее можно использовать в нескольких локальных MCP-клиентах, поддерживающих чтение переменных окружения. В каждом клиенте необходимо отдельно настроить использование этой переменной.
2. Настройте подключение в Codex
Добавьте MCP-сервер с именем, например, aw_bi. Укажите адрес вашей Системы с путем /mcp, например https://aw-demo.ru/mcp, и настройте чтение токена из переменной AW_BI_MCP_TOKEN.
3. Перезапустите клиент и проверьте подключение
Полностью закройте и снова запустите Codex. Для расширения Codex перезапустите IDE, а для запуска из терминала откройте новое окно терминала: команда setx не изменяет окружение уже запущенных процессов.
Введите /mcp, чтобы проверить подключенные серверы. Подробнее о настройках — в документации Codex.
Примеры работы с агентом¶
После подключения к MCP-серверу AW BI можно задавать агенту вопросы по данным виджетов и информационных панелей. Доступные инструменты (методы) и способы их использования можно уточнить у самого агента.
Запрос к данным¶
Задайте агенту вопрос по данным доступного вам виджета или информационной панели. Укажите, какие показатели нужно проанализировать, за какой период и с какими условиями отбора данных.
Агент использует инструменты подключенного сервера для получения данных и подготовки ответа. Содержание ответа зависит от запроса и доступных данных.
Дополнительный контекст для анализа¶
Для пояснения данных агенту доступны:
- информация о виджете — описание виджета независимо от режима его отображения;
- системный виджет Текст на информационной панели, в том числе на скрытых вкладках;
- общий SQL-фильтр виджета.
В Информации о виджете и системном виджете Текст можно указать назначение показателей, особенности расчета, условия фильтрации, связи между виджетами и ограничения данных. Эти пояснения помогают агенту интерпретировать результаты и учитывать условия анализа.
Особенности работы¶
При анализе данных учитывайте следующие особенности:
- агент получает данные через виджеты и не изменяет их настройки;
- получение данных выполняется по основной формуле показателя;
- при анализе панели агент использует данные виджетов и текстовые пояснения из описаний виджетов и системного виджета Текст. Нужные виджеты и показатели следует явно указать в запросе;
-
развернутая сводная таблица возвращает матрицу "строки × столбцы × показатели × итоги".
Например, при запросе трех строк результат может содержать сотни организаций в группах-столбцах и несколько показателей для каждой группы-строки. Объем такого ответа может достигать сотен тысяч токенов. Если языковая модель получает только сокращенную часть результата, полнота анализа не гарантируется.