Интеграция MCP (доступ ИИ-инструментов)¶

Turbo EA включает встроенный MCP-сервер (Model Context Protocol), который позволяет ИИ-инструментам — таким как Claude Desktop, GitHub Copilot, Cursor и VS Code — запрашивать данные вашей EA напрямую. Пользователи аутентифицируются через существующего SSO-провайдера, и каждый запрос учитывает их индивидуальные разрешения.

Эта функция необязательна и не запускается автоматически. Она требует настройки SSO, активации профиля MCP в Docker Compose и включения администратором в интерфейсе настроек.

Как это работает¶

ИИ-инструмент (Claude, Copilot и т.д.)
    │
    │  Протокол MCP (HTTP + SSE)
    ▼
MCP-сервер Turbo EA (:8001, внутренний)
    │
    │  OAuth 2.1 с PKCE
    │  делегирует вашему SSO-провайдеру
    ▼
Бэкенд Turbo EA (:8000)
    │
    │  RBAC для каждого пользователя
    ▼
PostgreSQL

Пользователь добавляет URL MCP-сервера в свой ИИ-инструмент.
При первом подключении ИИ-инструмент открывает окно браузера для SSO-аутентификации.
После входа MCP-сервер выдаёт собственный токен доступа (на основе JWT Turbo EA пользователя).
ИИ-инструмент использует этот токен для всех последующих запросов. Токены обновляются автоматически.
Каждый запрос проходит через обычную систему разрешений Turbo EA — пользователи видят только данные, к которым у них есть доступ.

Предварительные требования¶

Перед включением MCP у вас должно быть:

SSO настроен и работает — MCP делегирует аутентификацию вашему SSO-провайдеру (Microsoft Entra ID, Google Workspace, Okta или общий OIDC). См. руководство по Аутентификации и SSO.
HTTPS с публичным доменом — поток OAuth требует стабильного URI перенаправления. Разверните за обратным прокси с терминацией TLS (Caddy, Traefik, Cloudflare Tunnel и т.д.).

Настройка¶

Шаг 1: Запустите сервис MCP¶

MCP-сервер — это опциональный профиль Docker Compose. Добавьте --profile mcp к вашей команде запуска:

docker compose --profile mcp up --build -d

Это запускает легковесный Python-контейнер (порт 8001, только внутренний) рядом с бэкендом и фронтендом. Nginx автоматически проксирует запросы /mcp/ к нему.

Шаг 2: Настройте переменные окружения¶

Добавьте следующее в ваш файл .env:

TURBO_EA_PUBLIC_URL=https://your-domain.example.com
MCP_PUBLIC_URL=https://your-domain.example.com/mcp

Переменная	По умолчанию	Описание
`TURBO_EA_PUBLIC_URL`	`http://localhost:8920`	Публичный URL вашего экземпляра Turbo EA
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	Публичный URL MCP-сервера (используется в URI перенаправления OAuth)
`MCP_PORT`	`8001`	Внутренний порт MCP-контейнера (редко требует изменения)

Шаг 3: Добавьте URI перенаправления OAuth в ваше приложение SSO¶

В регистрации приложения вашего SSO-провайдера (том же, которое вы настроили для входа в Turbo EA) добавьте этот URI перенаправления:

https://your-domain.example.com/mcp/oauth/callback

Это необходимо для потока OAuth, который аутентифицирует пользователей при подключении из их ИИ-инструмента.

Шаг 4: Включите MCP в настройках администратора¶

Перейдите в Настройки в области администрирования и выберите вкладку ИИ.
Прокрутите до раздела Интеграция MCP (доступ ИИ-инструментов).
Переключите переключатель, чтобы включить MCP.
В интерфейсе отобразится URL MCP-сервера и инструкции по настройке, которыми можно поделиться с вашей командой.

Warning

Переключатель недоступен, если SSO не настроен. Сначала настройте SSO.

Подключение ИИ-инструментов¶

После включения MCP поделитесь URL MCP-сервера с вашей командой. Каждый пользователь добавляет его в свой ИИ-инструмент:

Claude Desktop¶

Откройте Настройки > Коннекторы > Добавить пользовательский коннектор.
Введите URL MCP-сервера: https://your-domain.example.com/mcp
Нажмите Подключить — откроется окно браузера для SSO-входа.
После аутентификации Claude может запрашивать данные вашей EA.

VS Code (GitHub Copilot / Cursor)¶

Добавьте в файл .vscode/mcp.json вашего рабочего пространства:

{
  "servers": {
    "turbo-ea": {
      "type": "http",
      "url": "https://your-domain.example.com/mcp/mcp"
    }
  }
}

Двойное /mcp/mcp намеренное — первое /mcp/ — это путь прокси Nginx, второе — конечная точка протокола MCP.

Локальное тестирование (режим stdio)¶

Для локальной разработки или тестирования без SSO/HTTPS вы можете запустить MCP-сервер в режиме stdio — Claude Desktop запускает его напрямую как локальный процесс.

1. Установите пакет MCP-сервера:

pip install ./mcp-server

2. Добавьте в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "your@email.com",
        "TURBO_EA_PASSWORD": "your-password"
      }
    }
  }
}

В этом режиме сервер аутентифицируется с помощью email/пароля и автоматически обновляет токен в фоновом режиме.

Доступные возможности¶

MCP-сервер предоставляет доступ только для чтения к данным EA. Он не может создавать, изменять или удалять что-либо.

Инструменты¶

Инструмент	Описание
`search_cards`	Поиск и фильтрация карточек по типу, статусу или свободному тексту
`get_card`	Получение полных деталей карточки по UUID
`get_card_relations`	Получение всех связей карточки
`get_card_hierarchy`	Получение предков и потомков карточки
`list_card_types`	Список всех типов карточек в метамодели
`get_relation_types`	Список типов связей, опционально отфильтрованный по типу карточки
`get_dashboard`	Получение данных панели KPI (количество, качество данных, утверждения)
`get_landscape`	Получение карточек, сгруппированных по связанному типу

Ресурсы¶

URI	Описание
`turbo-ea://types`	Все типы карточек в метамодели
`turbo-ea://relation-types`	Все типы связей
`turbo-ea://dashboard`	KPI панели управления и сводная статистика

Управляемые промпты¶

Промпт	Описание
`analyze_landscape`	Многоэтапный анализ: обзор панели, типы, связи
`find_card`	Поиск карточки по имени, получение деталей и связей
`explore_dependencies`	Картирование зависимостей карточки и того, что зависит от неё

Разрешения¶

Роль	Доступ
Администратор	Настройка параметров MCP (разрешение `admin.mcp`)
Все аутентифицированные пользователи	Запросы данных EA через MCP-сервер (с учётом существующих разрешений на уровне карточек и приложения)

Разрешение admin.mcp контролирует, кто может управлять настройками MCP. Оно доступно только роли «Администратор» по умолчанию. Пользовательским ролям можно предоставить это разрешение через страницу администрирования ролей.

Доступ к данным через MCP следует той же модели RBAC, что и веб-интерфейс — отдельных разрешений на данные, специфичных для MCP, не существует.

Безопасность¶

Аутентификация через SSO: пользователи аутентифицируются через корпоративного SSO-провайдера. MCP-сервер никогда не видит и не хранит пароли.
OAuth 2.1 с PKCE: поток аутентификации использует Proof Key for Code Exchange (S256) для предотвращения перехвата кода авторизации.
RBAC для каждого пользователя: каждый запрос MCP выполняется с разрешениями аутентифицированного пользователя. Общие сервисные аккаунты не используются.
Доступ только для чтения: MCP-сервер может только читать данные. Он не может создавать, обновлять или удалять карточки, связи или другие ресурсы.
Ротация токенов: токены доступа истекают через 1 час. Токены обновления действуют 30 дней. Коды авторизации одноразовые и истекают через 10 минут.
Только внутренний порт: MCP-контейнер открывает порт 8001 только во внутренней сети Docker. Весь внешний доступ идёт через обратный прокси Nginx.

Устранение неполадок¶

Проблема	Решение
Переключатель MCP недоступен в настройках	Сначала необходимо настроить SSO. Перейдите в Настройки > вкладка «Аутентификация» и настройте SSO-провайдера.
«host not found» в логах Nginx	Сервис MCP не запущен. Запустите его с помощью `docker compose --profile mcp up -d`. Конфигурация Nginx обрабатывает это корректно (ответ 502, без сбоя).
Обратный вызов OAuth не проходит	Убедитесь, что вы добавили `https://your-domain.example.com/mcp/oauth/callback` как URI перенаправления в регистрации приложения SSO.
ИИ-инструмент не может подключиться	Проверьте, что `MCP_PUBLIC_URL` соответствует URL, доступному с машины пользователя. Убедитесь, что HTTPS работает.
Пользователь получает пустые результаты	MCP учитывает разрешения RBAC. Если у пользователя ограниченный доступ, он увидит только карточки, разрешённые его ролью.
Подключение обрывается через 1 час	ИИ-инструмент должен обрабатывать обновление токена автоматически. Если нет, переподключитесь.