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

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

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

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

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

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

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

Перед включением 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 -d

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

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

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

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

Переменная	По умолчанию	Описание
`CANOPY_URL`	`http://backend:8000`	Внутренний URL бэкенда, с которым взаимодействует контейнер MCP (имя сервиса Docker — редко требует изменения).
`CANOPY_PUBLIC_URL`	`http://localhost:8920`	Публичный URL вашего экземпляра Canopy.
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	Публичный URL MCP-сервера (используется в URI перенаправления OAuth и в метаданных).
`MCP_PORT`	`8001`	Внутренний порт MCP-контейнера (редко требует изменения).

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

В регистрации приложения вашего SSO-провайдера (том же, которое вы настроили для входа в Canopy) добавьте этот 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": {
    "canopy": {
      "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": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "your-password"
      }
    }
  }
}

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

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

MCP-сервер предоставляет 47 инструментов: 30 инструментов чтения, разделённых на девять кластеров, и 17 инструментов записи (13 аддитивных, 4 деструктивных). Каждый инструмент несёт ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint), поэтому такие коннекторы, как Claude Desktop, могут отобразить степень деструктивности действия в своём интерфейсе ещё до того, как пользователь подтвердит вызов.

Безопасность записи через сухой прогон

Каждый инструмент записи по умолчанию использует dry_run=true. В этом режиме бэкенд выполняет каждый валидатор и резолвер, формирует полный план и затем откатывает транзакцию, поэтому ничего не сохраняется. ИИ-инструмент возвращает предварительный просмотр пользователю; только после явного подтверждения он должен повторно вызвать инструмент с dry_run=false, чтобы зафиксировать изменения. Это не позволяет излишне ретивому агенту молча создать сотни карточек на основе неверно истолкованной таблицы.

Для более крупных фиксаций предусмотрен второй барьер: любая фиксация, превышающая MCP_BATCH_CONFIRMATION_THRESHOLD (по умолчанию 20 строк), должна вернуть одноразовый confirm_token, выданный при предыдущем сухом прогоне. Срок действия токена — 15 минут. Это проверяется дважды — сначала обёрткой MCP ещё до обращения к бэкенду, а затем самим бэкендом на эндпоинте фиксации — поэтому клиент, пропустивший этап сухого прогона, не сможет незаметно протащить крупный, непроверенный пакет.

Пакеты мутаций (журнал аудита)

Каждый вызов записи — будь то сухой прогон или нет — открывает строку mutation_batches ещё до какого-либо изменения данных, и каждое сгенерированное им событие (создание карточки, добавление/изменение связи, публикация комментария и т.д.) помечается идентификатором этого пакета, именем вызвавшего инструмента и аутентифицированным пользователем. Инструмент get_change_history восстанавливает полное постсобытийное сравнение для пакета по его идентификатору, а rollback_batch может отменить изменения пакета (см. ниже). Это означает, что любое изменение, инициированное через MCP, можно точно проследить — кто именно, каким инструментом и когда его выполнил — в отличие от того же действия, выполненного через веб-интерфейс.

Инструменты чтения

Сервер предоставляет 30 инструментов чтения, разделённых на девять кластеров.

Карточки и метамодель

Инструмент	Описание
`search_cards`	Поиск и фильтрация карточек по типу, статусу или свободному тексту
`get_card`	Получение полных деталей карточки по UUID
`get_card_relations`	Получение всех связей, подключённых к карточке
`get_card_hierarchy`	Получение предков и потомков карточки
`list_card_types`	Список всех типов карточек в метамодели, с полями и конфигурацией
`get_relation_types`	Список типов связей, опционально отфильтрованный по типу карточки
`resolve_card_refs`	Предварительная проверка ссылок на карточки по имени (например, «Sales / Customer Mgmt / CRM») перед массовым импортом — показывает, какие ссылки определены однозначно, какие неоднозначны, а какие отсутствуют
`analyze_impact`	Многошаговый анализ влияния — обходит граф связей от карточки наружу на глубину до 3 переходов, группируя результат по глубине, с опциональными фильтрами по типу связи и типу карточки

Панели

Инструмент	Описание
`get_dashboard`	Панель KPI (количество, качество данных, утверждения, активность)
`get_landscape`	Карточки одного типа, сгруппированные по связанному типу

GRC — Реестр рисков

Инструмент	Описание
`list_risks`	Постраничный, фильтруемый список рисков EA (TOGAF, фаза G)
`get_risk`	Детали одного риска со связанными карточками и журналом аудита
`get_risk_metrics`	KPI + матрицы 4×4 «вероятность × воздействие» (начальная и остаточная)
`get_card_risks`	Все риски, в данный момент связанные с конкретной карточкой

GRC — Соответствие

Инструмент	Описание
`list_compliance_findings`	Находки соответствия, сгруппированные по регламенту (EU AI Act, GDPR, NIS2, DORA, SOC 2, ISO 27001)
`get_compliance_overview`	Оценки соответствия + матрица статуса по регламентам + метаданные последнего сканирования

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

Инструмент	Описание
`list_principles`	Опубликованные принципы EA (формулировка, обоснование, последствия)
`list_adrs`	Architecture Decision Records с фильтрацией по инициативе / карточке / статусу / поисковому запросу
`get_adr`	Один ADR с разделами, связанными карточками, связанными ADR и журналом подписей
`list_soaws`	Statements of Architecture Work для инициативы

Отчёты

Инструмент	Описание
`get_portfolio_report`	Данные пузырьковой диаграммы для типа карточек (по умолчанию: функциональное × техническое соответствие)
`get_cost_treemap`	Treemap затрат карточек, опционально сгруппированный по связанному типу
`get_capability_heatmap`	Иерархическая тепловая карта бизнес-возможностей
`get_data_quality_report`	Разбивка полноты данных по типам карточек

Контекст карточки

Инструмент	Описание
`get_card_stakeholders`	Пользователи + роли, назначенные на карточку
`get_card_comments`	Тред комментариев карточки
`get_card_documents`	Ссылки на документы, прикреплённые к карточке

Диаграммы

Инструмент	Описание
`list_diagrams`	Список произвольных диаграмм, опционально отфильтрованных по одной карточке
`get_diagram`	Получение одной диаграммы по идентификатору, включая её XML DrawIO

Аудит и история изменений

Инструмент	Описание
`get_change_history`	Поиск пакета мутаций по идентификатору (возвращает сам пакет и все события, сгенерированные в его рамках, по порядку), либо просмотр последних пакетов по инициатору, имени инструмента или источнику (`mcp` / `web` / `api`)

Все инструменты чтения ограничены RBAC аутентифицированного пользователя — viewer просто получит пустой список (или 403) для областей, к которым у него нет доступа; на уровне MCP не требуется никакой настройки для отдельных инструментов.

Инструменты записи

Сервер предоставляет 17 инструментов записи: 13 аддитивных (действия создания/обновления, не уничтожающие данные) и 4 деструктивных (могут перезаписать или удалить данные, хотя несколько из них сами по себе восстановимы — см. примечания ниже).

Карточки и жизненный цикл

Инструмент	Аннотация	Описание
`create_cards_bulk`	Аддитивный	Создаёт несколько карточек за один вызов из строк, извлечённых из артефакта (например, строк таблицы). Поддерживает ссылки на родителя по имени в пределах одного пакета с серверной топологической сортировкой.
`update_cards_bulk`	Аддитивный	Обновляет несколько карточек за один вызов — точечные изменения полей с построчным сравнением «до/после» при сухом прогоне. `attributes` полностью заменяется по каждой строке; `strict_attributes=true` отклоняет неизвестные ключи полей с подсказкой для исправления.
`transition_card_lifecycle`	Аддитивный	Переводит карточку через действия утверждения (`approve` / `reject` / `reset`), фазы жизненного цикла (`phaseIn` / `active` / `phaseOut` / `endOfLife`) или значения статуса (`ACTIVE` / `PHASING_IN` / `PHASING_OUT` / `END_OF_LIFE` / `ARCHIVED`). Если у вызывающего нет нужного разрешения, вместо явного отказа возвращает ответ `pending` со сквозной ссылкой в веб-интерфейс.
`archive_cards`	Деструктивный	Мягко удаляет (архивирует) одну или несколько карточек с предварительным просмотром каскадных последствий при сухом прогоне (дочерние карточки, осиротевшие связи). Архивированные карточки можно восстановить в течение 30 дней до автоматической очистки. Полное (безвозвратное) удаление намеренно не предоставляется через MCP.

Связи и диаграммы

Инструмент	Аннотация	Описание
`upsert_relations_bulk`	Деструктивный	Создаёт или удаляет связи между карточками. Операция `action: "delete"` по умолчанию отклоняется (см. защитные ограждения ниже) — именно поэтому инструмент помечен как деструктивный, хотя в большинстве случаев используется для создания.
`create_diagram`	Аддитивный	Создаёт произвольную диаграмму DrawIO, опционально связанную с существующими карточками по UUID.
`update_diagram`	Деструктивный	Обновляет XML, название, описание или связанные карточки существующей диаграммы — `drawio_xml` полностью заменяет содержимое холста.
`import_bpmn`	Аддитивный	Сохраняет диаграмму BPMN 2.0 для существующей карточки Бизнес-процесса, проходя рабочий процесс черновик → отправка → утверждение. Если подходящая карточка не найдена, возвращает ошибку `card_not_found`, указывающую на `create_cards_bulk`, вместо того чтобы молча создать скудную карточку.

GRC — Реестр рисков

Инструмент	Аннотация	Описание
`create_risks`	Аддитивный	Создаёт один или несколько рисков, опционально связывая затронутые карточки в том же вызове.
`update_risks`	Аддитивный	Изменяет существующие риски по идентификатору; при передаче `linked_card_ids` полностью заменяет набор связанных затронутых карточек.

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

Инструмент	Аннотация	Описание
`create_soaw`	Аддитивный	Создаёт Statement of Architecture Work для инициативы.
`create_adr`	Аддитивный	Создаёт Architecture Decision Record (по умолчанию в статусе `draft`).
`update_adr`	Аддитивный	Обновляет заголовок, разделы, статус или связанные карточки существующего ADR.
`sign_adr`	Аддитивный	Подписывает ADR. Если у вызывающего нет разрешения `adr.sign`, возвращает ответ `pending` со сквозной ссылкой.

Совместная работа

Инструмент	Аннотация	Описание
`add_card_comment`	Аддитивный	Публикует комментарий на карточке (опционально как ответ в треде).
`assign_stakeholders`	Аддитивный	Назначает или снимает роли заинтересованных лиц на карточках. У бэкенда нет массового эндпоинта для этого, поэтому инструмент выполняет операции по одной внутри единого пакета мутаций.

Аудит

Инструмент	Аннотация	Описание
`rollback_batch`	Деструктивный	Отменяет изменения, выполненные в рамках пакета мутаций, проходя его события в обратном порядке и применяя обратное действие для каждого. Поддерживает `card.created` / `card.updated` / `card.archived` / `card.restored` / `relation.created` / `relation.upserted`; остальные типы событий отображаются как `unsupported_events` в плане сухого прогона. Сам откат фиксируется как новый пакет, поэтому история никогда не стирается. Отказывает, если более поздний пакет затронул те же сущности — если не передан `force=true`, что требует разрешения `admin.events`.

Содержимое, сохранённое этими инструментами (текст комментариев, разделы ADR/SoAW), при последующем чтении считается недоверенными данными — сервер никогда не интерпретирует его как инструкции, а только отображает.

Типовой сценарий импорта артефактов

Когда пользователь делится таблицей с ИИ-агентом:

Агент вызывает list_card_types и get_relation_types, чтобы понять метамодель.
Агент разбирает таблицу (в собственном контексте, не в MCP) и формирует словари по строкам.
Опционально агент вызывает resolve_card_refs, чтобы проверить, что ссылки на родителя/связи по имени однозначно определены.
Агент вызывает create_cards_bulk(cards=…, dry_run=True) и показывает пользователю предварительный просмотр.
Пользователь подтверждает; агент вызывает снова с dry_run=False (возвращая confirm_token, если пакет превышает порог подтверждения), чтобы зафиксировать изменения.
Если присутствуют столбцы со связями, агент затем вызывает upsert_relations_bulk тем же циклом «сухой прогон / подтверждение».

Сам MCP-сервер никогда не разбирает загруженные файлы — вызывающий ИИ-инструмент читает исходный артефакт (таблицу, XML BPMN, XML DrawIO, PDF, изображение) в собственном контексте и отправляет уже структурированные строки.

Защитные ограждения для инструментов записи

Эшелонированная защита поверх сухого прогона, чтобы ошибка LLM не могла нанести массовый ущерб:

Ограничение размера на вызов. Инструменты записи MCP применяют значительно меньший предел, чем нижележащие эндпоинты Excel-импортёра: 200 карточек для create_cards_bulk / update_cards_bulk / archive_cards, 500 операций для upsert_relations_bulk. Этого достаточно для любой реалистичной загрузки одного артефакта и достаточно мало, чтобы предварительный просмотр сухого прогона оставался обозримым. Сами бэкенд-эндпоинты принимают до 2000/5000 для легитимного Excel-импортёра веб-интерфейса.
Токен подтверждения выше порога. Фиксации, затрагивающие более MCP_BATCH_CONFIRMATION_THRESHOLD строк (по умолчанию 20), должны вернуть confirm_token, выданный при предыдущем сухом прогоне. Проверяется как обёрткой MCP, так и бэкендом.
По умолчанию запрет на удаление связей. upsert_relations_bulk отклоняет операции action: "delete" — для удаления связей используйте веб-интерфейс, где действие фиксируется под идентификатором пользователя с явным журналом аудита. Операторы могут включить эту возможность через MCP_ALLOW_RELATION_DELETE=true.
Нет полного удаления. Набор инструментов намеренно не включает безвозвратное удаление карточек. archive_cards (мягкое удаление с 30-дневным окном восстановления) и rollback_batch — единственные способы удалить данные через MCP, и оба они защищены сухим прогоном и помечены как деструктивные. Любой будущий инструмент, выполняющий необратимую операцию, потребует предварительного обсуждения в формате RFC.
Аварийный выключатель. MCP_WRITES_ENABLED=false отключает все 17 инструментов записи без повторного развёртывания кода. 30 инструментов чтения продолжают работать.
Метка происхождения для аудита. Каждый запрос к бэкенду от MCP-сервера несёт заголовок X-Canopy-Origin: mcp (список разрешённых значений на стороне сервера ограничен {mcp, web, api} — любое другое значение отбрасывается). События, сгенерированные из этих запросов, помечаются origin: "mcp" в полезной нагрузке журнала аудита, чтобы администраторы могли отфильтровать записи, инициированные MCP, в журнале. Заголовок X-Canopy-Batch передаёт идентификатор текущего пакета мутаций через все вызовы в рамках одного обращения к инструменту.

Переменные окружения защитных ограждений на контейнере MCP:

Переменная	По умолчанию	Эффект
`MCP_WRITES_ENABLED`	`true`	Главный переключатель инструментов записи. `false` → MCP только для чтения.
`MCP_MAX_CARDS_PER_CALL`	`200`	Жёсткое ограничение строк на вызов для `create_cards_bulk`, `update_cards_bulk`, `archive_cards`.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Жёсткое ограничение операций `upsert_relations_bulk` на запрос.
`MCP_ALLOW_RELATION_DELETE`	`false`	При значении `true` `upsert_relations_bulk` принимает операции `action: "delete"`.
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	Количество строк, выше которого фиксация должна вернуть `confirm_token`, выданный при предыдущем сухом прогоне.
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	При значении `true` фиксация выше порога без соответствующего предшествующего сухого прогона в той же сессии отклоняется. Операторы могут отключить это для доверенных автоматизированных конвейеров.

Ресурсы

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

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

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

Разрешения

Роль	Доступ
Администратор	Настройка параметров MCP (разрешение `admin.mcp`). Полный доступ на чтение + запись через MCP.
Все аутентифицированные пользователи	Доступ на чтение управляется их существующим RBAC. Инструменты записи требуют соответствующего бэкенд-разрешения для выполняемого действия.

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

Разрешение	Что контролирует
`inventory.create`	`create_cards_bulk`
`inventory.edit`	`update_cards_bulk`, переходы жизненного цикла/статуса через `transition_card_lifecycle`
`inventory.approval_status`	Переходы утверждения (`approve` / `reject` / `reset`) через `transition_card_lifecycle`
`inventory.archive`	`archive_cards`
`relations.manage`	`upsert_relations_bulk`
`diagrams.manage`	`create_diagram`, `update_diagram`
`bpm.edit`	`import_bpmn` (черновик); для публикации дополнительно требуется `card.approval_status` на процессе, предоставляемое через роль заинтересованного лица `process_owner`, роль admin или bpm_admin
`risks.manage`	`create_risks`, `update_risks`
`comments.create`	`add_card_comment`
`stakeholders.manage`	`assign_stakeholders`
`soaw.create`	`create_soaw`
`adr.create`	`create_adr`, `update_adr`
`adr.sign`	`sign_adr`
`admin.events`	`rollback_batch(force=True)` — обход конфликта отката с более поздним пакетом

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

Некоторые инструменты записи вместо явного отказа мягко деградируют, если у вызывающего нет разрешения: transition_card_lifecycle и sign_adr возвращают ответ pending со сквозной ссылкой в веб-интерфейс, чтобы человек с нужным разрешением мог завершить действие там.

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

Аутентификация через SSO: пользователи аутентифицируются через корпоративного SSO-провайдера. MCP-сервер никогда не видит и не хранит пароли (в HTTP-режиме).
OAuth 2.1 с PKCE: поток аутентификации использует Proof Key for Code Exchange (S256) для предотвращения перехвата кода авторизации.
RBAC для каждого пользователя: каждый запрос MCP — чтение или запись — выполняется с разрешениями аутентифицированного пользователя. Общие сервисные аккаунты не используются.
Сухой прогон по умолчанию при записи: инструменты записи по умолчанию предлагают предварительный просмотр в режиме проверки-и-отката. ИИ-инструмент должен явно вызвать инструмент ещё раз с dry_run=false, прежде чем какие-либо данные будут сохранены, и каждое изменение фиксируется в аудите под идентификатором пользователя как часть пакета мутаций.
Барьер токена подтверждения для крупных фиксаций: фиксации выше настраиваемого порога строк требуют токен, выданный при предыдущем сухом прогоне, и проверяются независимо как обёрткой MCP, так и бэкендом.
Полный журнал аудита с возможностью отката: get_change_history восстанавливает сравнение по событиям для любого пакета по его идентификатору; rollback_batch может отменить поддерживаемые типы событий пакета, а сам откат фиксируется как новый, доступный для аудита пакет.
Никакого разбора файлов в MCP: сам MCP-сервер не принимает PDF, файлы Excel, изображения или другие двоичные артефакты. Вызывающий ИИ-инструмент разбирает их в собственном контексте и отправляет структурированные строки. Это сохраняет узкую поверхность атаки и не подвергает сервер некорректному двоичному вводу.
Нет полного удаления через MCP: безвозвратное удаление карточек не предоставляется как инструмент. Единственные пути удаления — archive_cards (мягкое удаление с 30-дневным окном восстановления) и rollback_batch.
Ротация токенов: токены доступа истекают через 1 час и упреждающе обновляются. Токены обновления действуют 30 дней. Коды авторизации одноразовые и истекают через 10 минут.
Только внутренний порт: MCP-контейнер открывает порт 8001 только во внутренней сети Docker. Весь внешний доступ идёт через обратный прокси Nginx.
Хранилище токенов на один экземпляр: токены OAuth хранятся в памяти контейнера MCP. При запуске нескольких реплик за балансировщиком нагрузки закрепляйте сессии за одним экземпляром или будьте готовы к тому, что пользователям потребуется повторно аутентифицироваться после отказа — токены не разделяются между репликами.

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

Проблема	Решение
Переключатель 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. Если у пользователя ограниченный доступ, он увидит только карточки, разрешённые его ролью.
Инструмент записи возвращает `writes_disabled`	На этом развёртывании установлено `MCP_WRITES_ENABLED=false`. Инструменты чтения продолжают работать; при необходимости попросите оператора снова включить запись.
Фиксация отклонена с `confirm_token_required`	Пакет превышает `MCP_BATCH_CONFIRMATION_THRESHOLD` строк. Сначала повторите вызов с `dry_run=true`, затем передайте возвращённый `confirm_token` обратно при вызове фиксации.
Подключение обрывается через 1 час	ИИ-инструмент должен обрабатывать обновление токена автоматически. Если нет, переподключитесь.

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

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

Настройка​

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

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

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

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

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

Claude Desktop​

VS Code (GitHub Copilot / Cursor)​

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

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

Безопасность записи через сухой прогон​

Пакеты мутаций (журнал аудита)​

Инструменты чтения​

Инструменты записи​

Типовой сценарий импорта артефактов​

Защитные ограждения для инструментов записи​

Ресурсы​

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

Разрешения​

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

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