Доступ для внешнего AI-агента (MCP)

Платформа умеет отдавать себя внешнему AI-агенту — Claude Code, Cursor, LM Studio и любому другому клиенту, который говорит на протоколе MCP. Агент подключается по токену и получает 90 инструментов: от списка источников до сборки дашборда со связями между виджетами.

Это не «помощник внутри интерфейса» — тот описан в разделе AI-помощник. Здесь платформа выступает инструментом для агента, который работает у вас на машине.

Что агент может делать

Всё, что может пользователь, чьим токеном он подключился, — и ровно в тех же границах:

• читать данные — выборки виджетов и дашбордов, значения полей, метаданные таблиц;
• собирать модель — заводить источники, добавлять таблицы и SQL-блоки, связывать их, создавать вычисляемые поля, иерархии и параметры;
• строить визуализации — создавать и менять виджеты, складывать дашборды, задавать раскладку и связи между плитками;
• настраивать оформление — заголовки, легенду, оси, цвета, карточку показателя, вид плиток на дашборде. Что именно доступно у конкретного типа, агент спрашивает сам: widget_style_options для виджета, dashboard_item_options для плитки — оба отдают список ключей с допустимыми значениями, которые затем передаются в settings;
• управлять загрузкой — настраивать извлечение, ставить расписание, запускать прогоны и смотреть их статус;
• раздавать доступ — выдавать и снимать права на объекты, смотреть правила видимости.

Полный перечень с параметрами — справочник инструментов.

Вычисляемые поля датасета агенту нужно раскрывать формулой

Собирая виджет, агент задаёт полки выражениями. Сослаться на вычисляемое поле датасета по имени — [Месяц] — нельзя: виджет ответит «field [Месяц] not found» и перечислит доступные имена. В выражении пишется сама формула поля, например DATETRUNC([orders.order_date], 'month'). Формулу отдаёт dataset_get — это поля, у которых она заполнена.

Как подключить

1. Выпустите токен в профиле, вкладка Доступ для ИИ — выпуск и управление токенами. Токен показывается один раз.

2. Пропишите адрес в клиенте. Сервис говорит по протоколу Streamable HTTP:

   http://<адрес-платформы>:3333/mcp

   Токен передаётся заголовком Authorization: Bearer dwmcp_… при каждом обращении. Сессия на сервере не хранится, поэтому переподключаться после перерыва не нужно.

3. Проверьте связь. Клиент запросит список инструментов; если их 90 и сервер назвался datawell, всё в порядке.

Через внешний домен нужен список разрешённых имён

Сервис защищается от подмены имени узла и по умолчанию принимает обращения только на localhost и 127.0.0.1. Когда он опубликован под доменом через обратный прокси, запрос приходит с этим доменом в заголовке Host и получает отказ 403 «Host … не разрешён».

Домены перечисляются администратором при развёртывании — в переменной DATAWELL_MCP_ALLOWED_HOSTS, через запятую. После её изменения сервис перезапускается.

Кому разрешено

Токен выпускается не всем:

Условие	Что означает
Тип учётной записи — создатель или исследователь	Наблюдателю MCP-доступ не выдаётся
Членство в группе Пользователи AI mcp	Администратор добавляет в неё тех, кому агент разрешён
Рубильник в настройках AI	Администратор может выключить выдачу токенов для всей установки

Если хотя бы одно условие не выполнено, вкладки Доступ для ИИ в профиле нет. Уже выданный токен тоже может перестать работать — тогда на обращение агента платформа отвечает отказом с причиной: токен приостановлен, отозван, истёк срок или снят доступ.

Выпуск и управление токенами

Токен выпускается в профиле, вкладка Доступ для ИИ:

1. Укажите Название — по нему видно, какому клиенту выдан токен.
2. Задайте Срок действия в днях. Поле пустое — срок по умолчанию, 90 дней; потолок — 365. Оба значения задаются при установке платформы, поэтому на вашей установке они могут быть другими: подсказка под полем показывает действующие.
3. Нажмите Создать токен.

Токен показывается один раз

Скопируйте значение сразу после создания — повторно посмотреть его нельзя, только выпустить новый.

Значение выглядит как dwmcp_ и длинная случайная строка. Платформа хранит не сам токен, а его хэш, поэтому посмотреть значение позже нельзя — в списке остаётся только окончание вида dwmcp_…04aw.

В таблице Мои токены видно название, маскированное значение, статус, срок действия и дату последнего использования. Действия над токеном — кнопки-иконки в конце строки. Пауза останавливает токен, и клиент по нему перестаёт получать данные; у приостановленного на её месте появляется воспроизведение, которое возвращает токен в работу. Корзина отзывает токен: это необратимо, отозванный токен не восстанавливается, нужен новый.

Как выглядит отказ у клиента

Отказ приходит на самом подключении: без рабочего токена агент не открывает сессию и не получает даже списка инструментов. Причина называется прямо — «Токен приостановлен владельцем», «Токен отозван», «Срок действия токена истёк» или «Этой учётной записи доступ к MCP не разрешён». Незнакомый токен получает общий отказ.

Ограничения:

• одновременно у одного пользователя не больше 10 действующих токенов;
• не больше 4 одновременных обращений к данным по одному токену: сверх этого агент получает отказ «Слишком много одновременных запросов к данным». Повторный запрос теми же аргументами в течение 5 секунд отдаёт прежний ответ, не обращаясь к платформе снова;
• бессрочных токенов не бывает: срок обязателен и ограничен максимумом, который задал администратор;
• срок можно только сократить — продлить выпущенный токен нельзя: платформа отвечает на такую попытку отказом «Срок действия можно только сократить, но не продлить». Нужен более долгий доступ — выпускайте новый токен.

Токен несёт ваши права, включая ограничения строк

Агент обращается к платформе от вашего имени: ему доступны те же источники, датасеты и виджеты, что и вам, и на него так же действуют правила видимости строк. Права на изменение и удаление объектов передаются вместе с остальными: всё, что вы можете удалить руками, агент по этому токену тоже может. Отдать токен коллеге — всё равно что отдать свою учётную запись. Если токен утёк, отзовите его в этой же таблице.

Как отозвать доступ за пользователя

Свои токены каждый ведёт сам: чужие в таблице Мои токены не показываются, и отдельного экрана «все токены организации» в текущей версии нет. Когда сотрудник уволился или его токен утёк, доступ снимает администратор — любым из трёх действий:

• отключить учётную запись — все её токены перестают работать сразу, клиент получает отказ «Доступ к MCP снят: у владельца токена больше нет права на MCP-токены либо его учётная запись отключена»;
• исключить пользователя из группы «Пользователи AI mcp» — с тем же результатом и тем же текстом;
• выключить MCP-токены целиком для всей платформы — AI-провайдер.

Проверка идёт на каждом обращении агента, поэтому изменение действует немедленно и не ждёт истечения срока токена.

Как устроена защита от случайных разрушений

Опасные операции — удаление датасета, виджета, дашборда, источника — выполняются в два шага. Первый вызов ничего не удаляет, а возвращает разбор последствий и требует подтверждения:

Действие не выполнено — нужно подтверждение.
Будет удалён виджет «Выручка по регионам» (id 1537, тип column).
Последствия:
- Восстановить виджет нельзя.
- На дашбордах, где он размещён, плитки останутся пустыми — с пометкой об удалённом виджете.
- Права, выданные на этот виджет, снимаются.
Чтобы выполнить, повторите вызов с параметром confirm: "Выручка по регионам"

Подтверждение — точное название объекта, а не «да». Агент, который не понял, что удаляет, подтвердить не сможет: название нужно взять из ответа и повторить дословно.

Готовые сценарии и встроенная справка

Кроме инструментов сервис отдаёт агенту два вида подсказок, и обращаться к ним отдельно не нужно — клиент получает их сам:

• пять готовых сценариев: посмотреть данные, собрать виджет, собрать дашборд, собрать модель, разобраться с доступом;
• семь справочных разделов — устройство платформы, чтение данных, сборка виджетов и дашбордов, модель данных, источники и извлечение, доступы, справочники. Тот же материал агент может запросить инструментом guide.

Благодаря этому агент не выдумывает порядок работы: правила языка формул, требования к полкам виджета и ограничения по кардинальности он берёт из справки платформы.

Ограничения

• Размер запроса — до 4 МБ. Больший запрос отклоняется.
• Повторные тяжёлые чтения гасятся: одинаковый read-only вызов, повторённый через несколько секунд, отдаёт прежний результат; любое изменение данных сбрасывает это.
• Одновременных обращений к данным на токен — не больше 4 — защита от зациклившегося агента.
• Блокировок при одновременном редактировании нет. Если объект правят агент и человек сразу, победит тот, кто сохранил последним.
• Правила видимости строк и полей MCP не меняет — их можно только прочитать.

Что дальше

• Справочник инструментов — все 90 инструментов по группам.
• AI-помощник — помощник внутри интерфейса, который пишет SQL по описанию.
• Управление доступом — что именно увидит агент под вашей учётной записью.