Files
MikrotikManager/docs/mcp-enable-guide.md
T
DenozordecandClaude Opus 5.5 c85f1a49a0 chore(docs): инструкция по включению MCP — наблюдение, подтверждения, автономность
Права портала, настройки сервера, три шага включения с переходами и
возвратом, срок прав владельца, часовой бюджет в объектах, срок плана,
защиты, временный допуск, Route AI без автоматического восстановления,
пауза, отзыв, аварийная остановка и частые отказы. Надписи сверены с
интерфейсом, числа и коды — с backend и контрактами.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-21 21:08:33 +07:00

26 KiB
Raw Blame History

Включение MCP: наблюдение → подтверждения → ограниченная автономность

Инструкция для администратора Manager. Она описывает, как дать внешнему AI-клиенту доступ через MCP в три шага, с проверкой на каждом шаге:

  1. Наблюдение: агент только читает.
  2. Подтверждения: агент готовит изменения, человек одобряет каждое.
  3. Ограниченная автономность: агент применяет изменения сам, в узкой области и в пределах лимитов.

По умолчанию всё выключено. После установки:

  • MCP выключен;
  • нет ни одного подключения;
  • профили Route AI выключены, автоматическое восстановление маршрутов недоступно.

Это закреплено тестом на свежей базе (integration.test.ts).

Названия в кавычках «…» — надписи в интерфейсе, раздел MCP в Manager.

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

Права в портале

Право Что даёт в разделе MCP
mm:mcp:read открыть раздел, смотреть подключения, обращения, планы и операции; «Обновить мои права» для своего подключения; разрешить OAuth-доступ
mm:mcp:approve «Подтвердить план» и «Отклонить». Нужны ещё права самой операции: например, для изменения сети — mm:network:write
mm:mcp:pause «Остановить автоматические изменения» на вкладке «Обзор»
mm:mcp:admin всё остальное: настройки, подключения, защиты, Route AI, OAuth-клиенты, сверка и восстановление

Подключению можно передать только те права, которые есть у его владельца. Иначе сохранение отклоняется: «Нельзя делегировать отсутствующие права». Менять политику подключения может только его владелец.

Настройки сервера

  • MCP_PUBLIC_URL — внешний адрес MCP, например https://manager.example/mcp.
    • Путь — ровно /mcp, без query и без логина в адресе.
    • Нужен HTTPS. HTTP допускается только для localhost, 127.0.0.1 и [::1].
    • При нарушении любого из правил MCP отвечает INVALID_CONFIGURATION (503).
  • MCP_STATE_DIR — каталог ключей и поколения доступа. Храните его на постоянном томе.
    • Если каталог потерян, при старте создаётся новое поколение.
    • Тогда все выданные токены и все неприменённые планы перестают действовать.
  • Аудит. Изменения начинаются только при доступном аудите, иначе вызов получает AUDIT_UNAVAILABLE.

Шаг 0. Разрешить обращения MCP

  1. «Настройки» → «Настройки MCP» → включите «Разрешить обращения MCP».
  2. Там же задайте сроки хранения:
    • «Хранение обращений, дней»: от 1 до 365, по умолчанию 30;
    • «Хранение аудита, дней»: от 30 до 3650, по умолчанию 180.

Пока флаг выключен:

  • любой токен получает MCP_DISABLED (503);
  • воркер не запускает контроллер Route AI и не проверяет расхождения конфигурации.

Шаг 1. Наблюдение

Цель: узнать, что агент читает и как часто, не давая ему ничего менять.

Создать подключение

«Подключения» → «Выдать доступ». Откроется окно «Новое подключение». В нём:

  • «Название» — по нему подключение видно в журналах.
  • «Срок действия (UTC)» — не больше года. Для первого шага достаточно нескольких дней.
  • «Режим управления» — «Наблюдатель». Он же выбран по умолчанию.
  • Серверы и операции — только те, что нужны агенту.
    • Операция, не выданная подключению, получает OPERATION_DENIED.
    • Сервер вне списка получает SERVER_DENIED.
    • Глобальные операции работают только с «Разрешить выбранные глобальные операции».
  • Права — только на чтение, например mm:servers:read.
  • Лимиты. На этом шаге хватит значений по умолчанию:
    Поле По умолчанию Отказ при превышении
    «Вызовов в минуту» 60 RATE_LIMITED
    «Одновременных чтений» 4 RATE_LIMITED
    «Изменений в час» 10 BUDGET_EXCEEDED
    «Серверов на план» 5 PLAN_LIMIT_EXCEEDED
    «Объектов на план» 100 PLAN_LIMIT_EXCEEDED

После сохранения появится «Одноразовый токен MCP». Он показывается один раз:

  1. Скопируйте токен в секреты AI-клиента.
  2. Нажмите «Закрыть и скрыть токен».

Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать.

Подключить клиента

Подходит любой MCP-клиент с транспортом Streamable HTTP. Настройки клиента:

  • адрес: MCP_PUBLIC_URL;
  • заголовок: Authorization: Bearer <токен>.

Формат настроек зависит от клиента. Держите токен в переменной окружения, а не в файле настроек.

Вход через OAuth вместо токена:

  1. «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента. В поле «Redirect URI, по одному на строку» укажите адреса точно.
  2. При запросе доступа владелец видит «Разрешение OAuth-доступа» и выбирает подключение.
  3. Клиент получает доступ ровно этого подключения, не шире.

Права владельца

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

  • при создании подключения;
  • при сохранении «Изменить разрешения»;
  • кнопкой «Обновить мои права».

Когда срок прошёл, любой вызов получает UNAUTHORIZED (401): «Подключение недействительно или требуется подтверждение прав владельца». Помогает только «Обновить мои права».

Если в портале отозвать сессии пользователя, Manager отзывает и его подключения MCP вместе с токенами и временными допусками.

Что агент может на этом шаге

  • Может вызывать операции чтения: каталоги, состояние, журналы.
    • Диагностику mm_server_terminal_diagnostic (ping и подобное). Она требует права mm:servers:write, хотя ничего не меняет.
    • Контрольные ping и traceroute пути mm_route_path_verify.
  • Не может ничего менять. Все *_plan, включая нагрузочный тест полосы mm_routing_measurement_plan, получают OBSERVER_WRITE_DENIED. План при этом не создаётся.

Где смотреть

  • «Обзор»: вызовы за 24 часа, ошибки и отказы.
  • «Обращения»: каждый вызов с результатом и причиной отказа. Есть фильтры по подключению, серверу и времени.
  • «Подключения» → «Проверка подключения и временные допуски» → «Проверить готовность доступа». Это проверочное чтение возможностей от имени подключения.

Когда переходить к шагу 2

  • Вы знаете, какие операции и серверы нужны агенту.
  • На вкладке «Обращения» нет неожиданных отказов OPERATION_DENIED, SERVER_DENIED и RATE_LIMITED.

Шаг 2. Подтверждения

Цель: агент готовит изменения, а человек видит каждое до записи на роутер.

Перевести подключение

«Подключения» → подключение → «Изменить разрешения»:

  • «Режим управления» — «С подтверждением».
  • Операции записи — добавьте нужные *_plan.
  • Права — добавьте права записи.
  • «Изменений в час». Бюджет считает изменяемые объекты, а не вызовы.
    • План, который не помещается в остаток бюджета, отклоняется до подтверждения с BUDGET_EXCEEDED.
    • Пример: удаление сервера IPsec на стенде меняет 11 объектов, при значении 10 оно не пройдёт никогда.
    • Ставьте значение не меньше самого большого ожидаемого плана, умноженного на число таких планов в час.

Сохранение не меняет токен. Оно увеличивает версию политики и аннулирует все неприменённые планы подключения. Возврат на шаг 1 делается так же: сменить режим на «Наблюдатель».

Как проходит изменение

  1. Агент вызывает *_plan. Manager читает роутер, строит план и проверяет политику.
  2. План получает состояние awaiting-approval. Он виден в «Планы и операции» → «Планы изменений», а на вкладке «Обзор» растёт счётчик «Ожидают подтверждения».
  3. Человек с mm:mcp:approve открывает план, проверяет изменения и нажимает «Подтвердить план» или «Отклонить». Подтверждение относится ровно к показанному плану.
  4. Агент вызывает mm_change_apply с ID плана. Применить план может и человек: «Применить план».
  5. Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через mm_operation_get.

У плана есть срок:

  • 5 минут для сетевых операций;
  • 15 минут для остальных;
  • для servers.poll и routing.community.switch — меньше, если раньше истекают данные, на которых построен план.

Истёкший план не применяется: «Срок плана истёк. Подготовьте новый план».

Переключение постоянного профиля Route AI подтверждает только владелец подключения.

Защита объектов

«Разрешения» → «Защищённые объекты» → «Добавить защиту». Варианты:

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

Защита не ограничивает чтение.

Ставьте защиту до перехода к шагу 3, в первую очередь:

  • на интерфейсы и адреса, через которые Manager управляет роутером;
  • на маршруты к нему.

«Проверка разрешений» на той же вкладке показывает решение политики для операции и объекта без выполнения.

Если результат не тот

«Планы и операции» → «Сверка и восстановление»:

  1. Укажите UUID операции и нажмите «Сверить состояние операции». Manager прочитает роутер.
  2. «Подготовить обратный план» создаёт отдельный план возврата. Он проходит те же проверки и подтверждение. Если объект после операции изменили извне, Manager откажет.

Когда переходить к шагу 3

  • Планы агента совпадают с тем, что вы ожидали.
  • Отклонённых планов нет или почти нет.
  • Операции доходят до «Результат проверен».
  • «Расхождения конфигурации» пусты.
  • Защиты стоят на всём, что агент менять не должен.

Шаг 3. Ограниченная автономность

Цель: агент применяет повторяющиеся изменения сам, в узкой области.

Перевести подключение

«Изменить разрешения» → «Режим управления» → «Автономный». Сразу сузьте остальное:

  • серверы и операции — только те, что агент применял на шаге 2;
  • «Срок действия (UTC)» — короткий;
  • «Изменений в час» и «Объектов на план» — по фактическому размеру планов шага 2, без лишнего запаса;
  • «Опасные действия» — оставьте «Всегда подтверждать».
    • «Автономно для явно выбранных действий» снимает подтверждение только с отмеченных опасных операций.
    • Какие операции опасные, видно в каталоге операций и в панели «Проверка разрешений».

Что по-прежнему требует человека

План без подтверждения не применяется. Подтверждение остаётся обязательным:

  • для объектов с защитой «Подтверждение человеком». «Запрет изменений» по-прежнему запрещает;
  • для опасных операций, кроме явно выбранных;
  • для операций, которые сами требуют человека: Manager помечает весь сервер или операцию защитой «Подтверждение человеком». Такой план остаётся в состоянии awaiting-approval.

Временный допуск

«Подключения» → «Проверка подключения и временные допуски» → «Выдать временный допуск». Допуск:

  • получает отдельный токен;
  • только сужает основной доступ: серверы, операции, глобальные действия;
  • действует не дольше 24 часов («Срок допуска, минут»);
  • снимается кнопкой «Отозвать допуск».

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

Срок работы без человека

Автономная работа ограничена правами владельца: до истечения токена портала, с которым он последний раз подтвердил права, и не дольше 24 часов после этого. Дольше агент без человека не работает. Это намеренно.

Постоянный контроллер Route AI

Отдельная функция: контроллер сам переключает маршруты по профилю.

«Route AI» → «Постоянный контроллер Route AI» → «Создать профиль».

Требования к подключению:

  • режим не «Наблюдатель»;
  • у владельца и у подключения есть mm:network:read, mm:network:write и mm:filters:write;
  • серверы профиля входят в область подключения.

Требования к допуску:

  • «Допуск действует до (UTC, максимум 24 часа)»;
  • срок не позже срока токена, подключения и прав владельца.

Профиль отдельной таблицы или VRF:

  • нужна явная BGP-привязка;
  • у каждого пути — контрольная проба с исходным адресом.

Автоматическое восстановление недоступно. Профиль с ним отклоняется: ROUTE_RECOVERY_EXECUTOR_UNAVAILABLE. Нет источника событий RouterOS, который замечает пропуски.

Контроллер останавливается сам:

  • когда истёк допуск;
  • при «Обновить мои права» владельца подключения;
  • при обнаружении расхождения конфигурации у операций этого подключения;
  • при «Остановить автоматические изменения».

Пока MCP выключен, контроллер не работает.

Проверить путь вручную, без переключения: «Контрольная проверка пути».

Остановить, приостановить, отозвать

Действие Где Что происходит Обратимо
«Пауза» «Подключения» Токены подключения не принимаются, неприменённые планы аннулируются да, «Включить»
«Отозвать» «Подключения» Подключение и все его токены отозваны, неприменённые планы аннулируются нет: CONNECTION_REVOKED
«Новый токен» «Подключения» Старый токен перестаёт работать —
«Отозвать допуск» «Проверка подключения и временные допуски» Временный допуск и его токен перестают действовать нет
Снять «Разрешить обращения MCP» «Настройки» Все вызовы получают MCP_DISABLED, контроллер и проверка расхождений не работают. Токены не отзываются да: после включения токены снова работают
«Остановить автоматические изменения» «Обзор», право mm:mcp:pause MCP выключается, все профили Route AI выключаются. Начатые записи завершаются или сверяются частично: MCP включается флагом, профили Route AI включают заново вручную
«Отключить и отозвать токены» «Настройки» → «OAuth-клиенты» OAuth-клиент отключён, его токены отозваны нет

После работы с агентом, которому доступ больше не нужен, — «Отозвать», а не «Пауза».

Частые отказы

Код Причина Что делать
MCP_DISABLED MCP выключен «Разрешить обращения MCP»
UNAUTHORIZED Токен неверный, отозван или истёк, подключение на паузе, права владельца не подтверждены или сменилось поколение доступа проверить подключение, «Обновить мои права», при необходимости «Новый токен»
OPERATION_DENIED Операция не выдана подключению добавить операцию в «Изменить разрешения»
OWNER_PERMISSION_MISSING, CONNECTION_PERMISSION_MISSING Нет права у владельца или у подключения выдать право в портале или подключению
SERVER_DENIED, GLOBAL_DENIED Сервер вне области, глобальные операции не разрешены расширить область, если это нужно
GRANT_INACTIVE, GRANT_SCOPE_DENIED Временный допуск истёк или запрос шире допуска новый допуск
RATE_LIMITED Минутный лимит вызовов или одновременных чтений поднять лимит или замедлить клиента
OBSERVER_WRITE_DENIED Изменение в режиме «Наблюдатель» перейти на шаг 2
BUDGET_EXCEEDED План не помещается в часовой бюджет изменений подождать или поднять «Изменений в час»
PLAN_LIMIT_EXCEEDED Слишком много серверов или объектов в плане разбить план или поднять лимит
PROTECTED_OBJECT Объект под «Запрет изменений» снять защиту, если изменение действительно нужно
AUDIT_UNAVAILABLE Аудит недоступен восстановить базу или аудит; изменения до этого не выполняются
PLAN_EXPIRED Истёк срок плана или исходных данных подготовить новый план
CONFIGURATION_BUSY Глобальная конфигурация занята другой операцией дольше 30 секунд повторить позже

Что проверено

Доказательства и статусы по каждому критерию — в mcp-final-manifest.md.

  • Режим «С подтверждением» проверен на стенде.
    • IPsec: пять прогонов подряд, в каждом 4 подтверждения в интерфейсе. Применение без подтверждения отклонено.
    • Маршрутизация A3: 2 подтверждения.
    • Выдача токена в интерфейсе, подтверждение плана и подписанный отзыв в настоящих Manager и Portal — EXT-1.
  • Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты покрыты тестами политики (policy.test.ts). На стенде отдельно не проверялись.
  • Раздел MCP в интерфейсе проверен частично: выдача ограниченного доступа, отказы, фильтры и пагинация на стенде не проверялись (UI-1).
  • Автоматическое восстановление маршрутов не реализовано и выключено (этап 4 плана завершения).