/
Подключение Cortex к ИИ-ассистенту через MCP

Подключение Cortex к ИИ-ассистенту через MCP

Введение

MCP (Model Context Protocol) – это открытый протокол, который позволяет подключать внешних ИИ-ассистентов, таких как, например, Cursor или Claude Code, напрямую к платформе Visiology. Например, вы задаёте ассистенту вопрос на естественном языке: «Какая выручка за март по Москве?». Ассистент самостоятельно находит нужный дашборд, применяет фильтры, считывает данные в рамках ваших прав доступа и возвращает ответ.

Данное руководство предназначено для конечного пользователя. Предполагается, что администратор уже развернул Cortex и предоставил вам URL MCP-сервера (например, https://my-visiology/v3/mcp).

Подготовка к работе

Получение данных от администратора

Для подключения вам понадобятся следующие данные:

  • URL MCP-сервера в формате https://<адрес_платформы>/v3/mcp.

  • Учётная запись в Visiology (логин и пароль). При первом подключении браузер запросит авторизацию.

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

Способ проверки зависит от вашего MCP-клиента:

  • Claude Code: В поле ввода наберите символ /. В выпадающем меню должны появиться команды с префиксом /visiology-cortex. Выберите команду authenticate. Ассистент вернёт ваш user_id, name и параметры OAuth, что подтвердит успешную связь.

  • Cursor: Перейдите в Settings → MCP Servers. Рядом с visiology-cortex должна загореться зелёная точка, что означает успешное подключение и загрузку доступных инструментов. Slash-команды в Cursor также начинаются с префикса /visiology-cortex, но их поддержка может быть частичной.
    Примечание: Если ваш администратор назвал MCP-сервер иначе (не visiology-cortex), то префикс slash-команд будет соответствующим.

Настройка самоподписанных сертификатов

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

Чтобы это исправить:

  1. Получите файл сертификата.
    Запросите у администратора платформы файл сертификата (с расширением .pem или .crt) и сохраните его на компьютере, например в свою домашнюю папку.

  2. Укажите путь к сертификату.
    Windows – откройте PowerShell и выполните следующую команду (подставив свой путь к файлу):

    setx NODE_EXTRA_CA_CERTS "C:\Users\ВашеИмя\visiology-ca.pem"

    После этого закройте и снова откройте терминал или приложение MCP-сервера - иначе изменение не подхватится.
    Linux / macOS – добавьте строку в файл ~/.bashrc (или ~/.zshrc):

    export NODE_EXTRA_CA_CERTS="$HOME/visiology-ca.pem"

    Затем перезапустите терминал.

Настройка подключений в различных MCP-клиентах

Cursor

  1. Перейдите в меню File > Preferences > Cursor Settings > Tools & MCPs.

  2. Нажмите Add new MCP server и укажите следующую конфигурацию:

    { "visiology-cortex": { "type": "streamable-http", "url": "https://<адрес_платформы>/v3/mcp" } }

    После добавления Cursor автоматически перечитает конфигурацию.

Claude Code

Выполните следующую команду:

claude mcp add --transport http visiology-cortex <https://<platform-host>>/v3/mcp

Codex

Выполните следующую команду:

codex mcp add visiology-cortex --url <https://<platform-host>>/v3/mcp

Другой MCP-клиент

Если ваш клиент поддерживает спецификацию MCP и транспорт streamable-http, просто укажите URL https://<адрес_платформы>/v3/mcp. Аутентификация будет выполнена автоматически по протоколу OAuth 2.1 через Keycloak: при первом запросе откроется браузер для входа.

Авторизация и обновление токенов

Как происходит авторизация

Cortex MCP-сервер использует стандартный OAuth-механизм, встроенный в протокол MCP. Процесс инициируется вашим MCP-клиентом (ИИ-ассистентом) и выглядит так:

  • MCP-клиент формирует специальную ссылку для авторизации.

  • Вам нужно открыть эту ссылку в браузере (клиент может предложить сделать это сам, например, Cursor показывает кнопку «Authorize», а Claude выводит URL в консоль или диалог).

  • Вы проходите авторизацию.

  • После успешного входа браузер перенаправляется обратно на локальный адрес, и MCP-клиент получает токены доступа.

Важно: Для корректной работы авторизации в настройках клиента MCP должен быть указан корректный путь до сервера ваш-сервер/v3/mcp.

Обновление токена

После успешной авторизации MCP-клиент автоматически обновляет токен в течение всей сессии. Вам не нужно предпринимать никаких дополнительных действий – refresh-токен используется прозрачно.

Когда требуется повторная авторизация

Повторная авторизация потребуется только в одном случае: если сессия на сервере полностью истекла (например, после длительного перерыва в работе).

MCP-сервер предупредит об этом при первой попытке вызвать какой-либо инструмент – вы увидите сообщение о необходимости авторизоваться заново. Просто повторите шаги из раздела «Как происходит авторизация».

Быстрые команды через /

Если ассистент неверно интерпретирует ваш запрос и использует не тот инструмент (например, отвечает «не могу» на вопрос о дашборде), вы можете вызвать нужный инструмент напрямую.

Чтобы использовать прямую команду:

  1. Наберите символ / в поле ввода чата.

  2. В выпадающем меню появятся команды с префиксом /visiology-cortex (если сервер назван иначе, префикс будет соответствующим).

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

Доступные команды Cortex:

Команда

Slash-команда

Действие

Команда

Slash-команда

Действие

Основные (вызывают внутренние команды, которые работают на модели, к которой подключена Visiology Cortex)

ask_analytics

/ask_question

Аналитический вопрос по данным (Cortex сам найдёт дашборд).

ask_documentation

/ask_docs

Вопросы по документации.

ask_dax_measure

/consult_dax

Консультация по DAX-мерам.

ask_widget_code

/consult_widget_code

Консультация по JS-коду виджета.

ask_sql_assistant

/consult_sql_assistant

Консультация по SQL для Self-Service ETL.

ask_widget_settings

/consult_widget_settings

Консультация по оформлению виджета.

Дополнительные (работают с моделью, которая подключена к вашему ИИ-ассистенту)

list_dashboards

/search_dashboards

Семантический поиск дашборда по описанию.

После открытия сессии дашборда

open_dashboard

/open_dashboard_session

Открыть дашборд для ручной работы.

set_filter

–

Применить фильтр по виджету.

set_date_filter

–

Применить date-фильтр (LLM вызывает сам).

get_widget_data

–

Прочитать отфильтрованные данные виджета (LLM вызывает сам).

close_dashboard

–

Закрыть сессию в браузере (LLM вызывает сам).

Диагностика

authenticate

–

Проверка авторизации.

Инструменты get_widget_data, set_date_filter и close_dashboard вызываются LLM автоматически, исходя из контекста, и не вынесены в быстрые команды.

Рекомендации по использованию с несколькими MCP-серверами

Если у вас одновременно подключено несколько MCP-серверов (например, Slack, Jira, GitHub и Cortex), ассистент может некорректно направлять запросы. Например, вопрос «Какая выручка за март?» может быть отправлен в Jira.

Чтобы избежать этого, добавьте в ассистента системную инструкцию, которая явно указывает, что вопросы о BI, данных и дашбордах относятся к Cortex.

Где задать инструкцию

Клиент

Расположение

Клиент

Расположение

Cursor

Settings → Rules (User Rules или Project Rules).

Claude Code

Файл CLAUDE.md в корне проекта или ~/.claude/CLAUDE.md.

Кастомный клиент

Параметр system= вашего запроса к LLM.

Текст инструкции

У тебя подключён Visiology Cortex — BI-система компании. Когда пользователь задаёт вопрос про: - данные, отчёты, показатели, метрики, KPI - выручку, продажи, план/факт, маржинальность - дашборды или листы Visiology (например «дашборд ДСТ», «лист продажи») - DAX, меры, ColumnChart/Highcharts/DataGrid, JS-код виджета - настройку платформы Visiology — ТЫ ДОЛЖЕН использовать инструменты Cortex MCP (ask_analytics, list_dashboards, ask_dax_measure, ask_widget_code, ask_documentation), а не инструменты других подключённых MCP-серверов. Правила выбора инструмента внутри Cortex: 1. Простой аналитический вопрос («Какая выручка за март?», «Сравни Москва vs СПб») → ask_analytics. Он сам найдёт дашборд, применит фильтры и ответит. 2. Поиск дашборда по описанию («Найди дашборд по продажам») → list_dashboards. Возвращает ОДИН самый релевантный. 3. Ручная работа с дашбордом (пробовать фильтры вручную, читать сырые строки) → open_dashboard → set_filter / set_date_filter → get_widget_data → close_dashboard. Медленнее (~30с на открытие), но полный контроль. 4. set_filter / set_date_filter / get_widget_data работают только в уже открытой сессии open_dashboard. 5. «Напиши DAX…» → ask_dax_measure «Как сделать drill-down в Highcharts?» → ask_widget_code (укажи widget_type) «Как настроить роли?» → ask_documentation Если нет явного указания на ручное управление — предпочитай ask_analytics: быстрее и покрывает большинство сценариев. Формат ответа мне: значение + единицы + период + применённые фильтры + источник (какой дашборд / лист). Никогда не додумывай цифры — только то, что получено от инструмента. Если данных недостаточно — скажи явно, чего не хватает и какой следующий шаг нужен.

Рекомендации по формулировке запросов

Корректная формулировка запроса значительно повышает точность ответа ассистента.

Хорошие формулировки

Формулировка

Почему работает

Формулировка

Почему работает

«Какая выручка за март 2026 по филиалу Москва?»

Чётко указан период и срез данных.

«Сравни выручку Q1 2026 vs Q1 2025 по регионам»

Есть сравнение и явные периоды.

«Открой дашборд продаж и покажи первые 10 строк с фильтром Москва»

Описан явный рабочий процесс, агенту понятно, что нужна цепочка действий.

«Покажи дашборд с потребностью в технике»

Агент вызовет list_dashboards.

«Как написать DAX-меру для нарастающего итога по продажам?»

Запрос явно направляет в ask_dax_measure.

Проблемные формулировки

Формулировка

Почему не сработает

Формулировка

Почему не сработает

«Расскажи всё, что знаешь о продажах»

Слишком широко, непонятно, какой срез данных нужен.

«Посчитай за прошлый месяц»

«Прошлый» – неоднозначное понятие. Всегда указывайте конкретные даты.

«Сделай дашборд про X»

Cortex не создаёт дашборды, а только читает данные.

«Запомни этот отчёт для следующего раза»

Cortex не хранит информацию между сессиями.

Диагностика неисправностей

Перед обращением к администратору пройдитесь по этой таблице:

Симптом

Что проверить

Симптом

Что проверить

Браузер не открывается при первом запросе

Проверьте URL в конфигурации. Откройте в браузере https://<адрес_платформы>/v3/mcp/.well-known/oauth-protected-resource – должен вернуться JSON с полями resource, authorization_servers, scopes_supported. Если получен код 404, администратор не запустил MCP-сервер.

Долгое открытие браузера или зависание

Обычно Keycloak отвечает за 1–2 секунды. Если задержка заметно дольше — возможна сетевая задержка до платформы.

Браузер открылся, Keycloak отвечает Invalid scopes / Host not trusted / Policy rejected

На стенде что-то пошло не так с автоматическим созданием клиента visiology_mcp_client в Keycloak. Скопируйте из URL ошибки параметр client_id и текст ошибки и передайте администратору вместе со ссылкой на техническую страницу.

Открылся браузер с Keycloak, но авторизация не проходит

Проверьте правильность логина и пароля. Попробуйте зайти на портал Visiology с теми же учётными данными.

Авторизация прошла, но ассистент «не видит» Cortex

Проверьте URL в конфигурации клиента и индикатор подключения (в Cursor: зелёная точка в Settings → MCP Servers; в Claude Desktop: значок MCP под полем ввода). Введите / — команды с префиксом /visiology-cortex должны быть в списке. Перезапустите клиент.

Ассистент возвращает «нет доступа к дашборду»

У вашего пользователя в Visiology нет прав на этот дашборд. Cortex соблюдает политики контроля доступа (ACL) платформы.

Вопрос «Какая выручка?» направляется в Slack/Jira, а не в Cortex

Добавьте системную инструкцию (см. раздел «Рекомендации по использованию с несколькими MCP-серверами») и перезапустите чат.

На аналитический вопрос получен пустой ответ или сообщение «не нашёл данных»

Уточните период, название дашборда или показателя. Часто помогает явное указание, например: «в дашборде ДСТ».

Сессия обрывается через 30 минут простоя

MCP-сервер рекламирует параметр offline_access, что позволяет клиенту получать refresh-токен и автоматически обновлять access-токен в фоновом режиме. Если этого не происходит — обратитесь к администратору.

Любой запрос отвечает ошибкой [no_user_access]

У вашего пользователя в Visiology выключен доступ к Cortex (на уровне пользователя или группы). Обратитесь к администратору – он включит доступ в панели администратора Visiology.

Любой запрос отвечает [RATE_LIMITED] с подсказкой retry_after_sec=N

Превышен лимит запросов на пользователя:

  • Аналитические вопросы (ask_*, open_dashboard) – 30 запросов/мин

  • Лёгкие операции (list_dashboards, set_filter, get_widget_data, close_dashboard, set_date_filter) – 120 запросов/мин. Подождите указанное количество секунд и повторите попытку.

Если перечисленные действия не помогли решить проблему, обратитесь к администратору Visiology. Технические детали для администратора приведены ниже.

Редкий сценарий: кастомный клиент на MCP SDK, которому требуется программно передать client_id. В этом случае используйте значение visiology_mcp_client. Это публичный клиент (token_endpoint_auth_method: none) с PKCE S256.

Ограничения и особенности

  • Cortex только читает данные: Cortex не создаёт и не изменяет дашборды, не меняет модель данных и не загружает новые источники.

  • Соблюдение прав доступа: Все запросы выполняются строго в рамках ваших прав доступа. Если у вас нет прав на дашборд, Cortex не сможет его отобразить или считать данные.

  • Ограничение на количество одновременных сессий: Вы можете открыть не более 5 дашбордов в браузерных сессиях одновременно.

  • Таймаут сессии: Сессия с открытым дашбордом автоматически закрывается после 5 минут бездействия.

  • Проверяемость данных: Ассистент никогда не «додумывает» цифры. Любое число в ответе всегда получено из конкретного виджета конкретного дашборда, и источник данных указывается в ответе.

Нужна дополнительная помощь?

Свяжитесь с технической поддержкой.

Смотрите также

Параметры config.json для MCP-сервера
Visiology Cortex