Как подключить Prizma BI к ИИ-агенту через MCP

MCP позволяет ИИ-агенту получать данные из Prizma BI по потоковому HTTP-соединению. Сервер применяет права пользователя: агент не получает доступ к рабочему пространству, дашборду или набору данных, которые недоступны пользователю.

Версия текущего контракта: v1.

Перед началом

Вам понадобятся:

• аккаунт Prizma BI;
• доступ к нужному рабочему пространству и опубликованным данным;
• MCP-клиент с поддержкой потокового HTTP-соединения;
• токен пользователя с минимально необходимыми правами.

Не вставляйте токен в текст запроса к агенту, публичный чат, репозиторий или логи. Передавайте его только через защищённую настройку секретов MCP-клиента.

Настройка подключения

Укажите в MCP-клиенте адрес сервера:

https://<mcp-host>/mcp

Для локального запуска используйте MCP-точку входа на loopback-подключении и порту 8090. Адрес рабочей инсталляции зависит от окружения и должен быть выдан администратором Prizma BI.

Добавьте заголовок авторизации:

Authorization: Bearer <token>

После подключения сначала запросите список доступных рабочих пространств. Не начинайте аналитический запрос, пока не проверите область доступа пользователя.

Доступные инструменты

list_workspaces

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

{}

search

Ищет доступные дашборды и отчёты. Поиск ограничен разрешённой областью рабочего пространства пользователя и никогда не обращается к произвольным коллекциям Directus. Можно отфильтровать типы объектов и установить ограничение не больше 50.

{"query":"выручка","types":["dashboard","report"],"limit":20}

get_dashboard

Возвращает дашборд по публичному идентификатору dashboardId. Внутренний идентификатор базы данных использовать нельзя. Для отсутствующего и недоступного дашборда сервер возвращает одинаковую безопасную ошибку.

{"dashboardId":"sales-overview"}

list_notifications

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

{"limit":20}

list_alerts

Возвращает доступные оповещения. Результаты ограничены разрешённой областью рабочего пространства, а лимит применяется на сервере.

{"limit":20}

get_report

Возвращает отчёт по публичному идентификатору вместе с разрешённым определением отчёта и каталогом полей набора данных. Для отсутствующего и недоступного отчёта сервер возвращает одинаковую безопасную ошибку.

{"reportId":"revenue-by-month"}

run_query

Выполняет структурированный запрос только для чтения по опубликованному набору данных. Исходный SQL, неизвестные поля и обход политик построчного или поколоночного доступа не поддерживаются.

{
  "dataset": "sales",
  "dimensions": ["month"],
  "measures": ["revenue"],
  "filters": [],
  "orderBy": [],
  "limit": 100
}

Точную схему параметров MCP-клиент получает через tools/list. Не копируйте поля из примера, если они отсутствуют в актуальной схеме конкретной версии сервера.

download_export

Скачивает вашу готовую выгрузку по workspace и exportId из list_exports / get_export_status. Ответ содержит байты файла в resource.blob (base64), имя — в structuredContent.fileName. URI вложения не является публичной ссылкой. Нужны актуальные права на пространство, датасет и выгрузку; файл читается тем же пользовательским токеном. Большие файлы скачивайте через интерфейс Призмы.

Анализ выполняйте через платформу без выгрузки. Файл нужен по явной просьбе пользователя или при объяснённой необходимости.

Создание отчётов и дашбордов

preview_create_report проверяет рабочее пространство, команду и датасет текущим пользовательским доступом. Передайте workspace и team (публичные идентификаторы из list_workspaces), title, description (строка или null), dataset, dimensions, measures, filters, order и chartType. Поля берите только из свежего get_dataset.members[].id: поддержаны корневые canonical member IDs, не внутренние UUID, не подписи и не связанные поля. Нужен хотя бы один показатель. Сохраняются плоская таблица, выбранные поля, дерево фильтров и порядок; результат — черновик с первой ревизией. Новые папки, публикация, сводные таблицы и редактирование существующих отчётов этим инструментом не выполняются.

preview_create_dashboard принимает только workspace, team, title, description. Создаётся пустой черновик без виджетов; заполненный дашборд этот контракт не строит.

Покажите пользователю точный предпросмотр. Только после явного согласия вызовите create_report или create_dashboard с тем же request, выданным previewId, confirm: true и уникальным idempotencyKey (8–200 символов). Предпросмотр одноразовый и действует 120 секунд. Встроенный чат дополнительно требует штатное серверное подтверждение. Успех возвращает публичный идентификатор и ссылку после точного чтения созданной записи. Повтор того же ключа возвращает сохранённый результат, а не создаёт второй объект. При неопределённом исходе не меняйте ключ и не создавайте новый предпросмотр ради повтора: сначала проверьте библиотеку; для незавершённых операций требуется сверка оператором.

Нужны включённые изменения на сервере, хранилище идемпотентности и отдельно выданные mcp:reports:create / mcp:dashboards:create на согласованном пользовательском target. Обычный read-доступ и глобальный режим чтения их не выдают. Обычные права Directus и проверки пространства/датасета сохраняются. STDIO остаётся только для чтения. Выдача прав и включение production не выполняются установкой этих инструментов.

Актуальные идентификаторы инструментов

Ниже приведён полный список идентификаторов, который проверяется при сборке документации. Описание параметров для конкретной установки всегда берите из tools/list.

list_notifications, list_alerts, get_alert, list_activity, list_datasets, get_distinct_values, run_query, run_report, run_widget, get_dataset, validate_query, explain_query, get_dashboard, get_report, list_exports, get_export_status, download_export, preview_export, mark_notification_read, mark_all_notifications_read, request_export, list_workspaces, search, get_library, list_favorites, get_default_dashboard, add_favorite, remove_favorite, preview_create_report, create_report, preview_create_dashboard, create_dashboard

Что сейчас не поддерживается

Доступны ресурсы prizma://capabilities, prizma://glossary и каталог датасета. Инструменты не предоставляют произвольный CRUD, удаление объектов, исходный SQL, управление пользователями или выдачу токенов. Изменения ограничены явно зарегистрированными операциями с отдельными правами и подтверждением.

Не делайте вывод о наличии возможности только по названию продукта: проверяйте актуальный ответ tools/list.

Безопасность и ограничения

• Инструменты разделены на чтение и ограниченные операции в рамках прав пользователя. Не предполагайте, что инструмент доступен или изменяет данные: перед вызовом всегда проверяйте актуальную схему через tools/list.
• Проверка доступа выполняется на стороне Prizma BI для каждого вызова.
• Не передавайте в запросах секреты, токены или персональные данные, не необходимые для задачи.
• Не просите агента обходить политики построчного или поколоночного доступа и не подбирайте идентификаторы объектов.
• Ошибки доступа намеренно не раскрывают, существует ли недоступный объект.
• Для рабочей среды необходимы защита точки входа, ограничение частоты, аудит, метрики и хранилище состояния сессий; текущий транспорт рассчитан на тестовый и первый рабочий сценарий.

Проверка подключения

1. Выполните tools/list и убедитесь, что видите list_workspaces, search, get_dashboard, list_notifications, list_alerts, get_report и run_query.
2. Вызовите list_workspaces без аргументов.
3. Выберите доступный публичный идентификатор дашборда.
4. Выполните небольшой run_query с ограничением до 100 строк.
5. Проверьте, что результат соответствует правам пользователя.

Если подключение не работает, проверьте адрес /mcp, токен, срок его действия и доступность сервера. Не добавляйте токен в обращение в поддержку; передайте только время ошибки и обезличенное описание клиента.

Что дальше

Начните с быстрого старта, затем изучите работу с отчётами. Вопросы по доступам отправляйте администратору рабочего пространства.

{
  "query": "выручка",
  "types": ["dashboard", "report"],
  "limit": 20
}

Authorization: Bearer <token>