Files
MikrotikManager/docs/mcp-enable-guide.md
T
DenozordecandClaude Opus 5.5 c1abfffe26 chore(docs): пользовательская документация MCP вместо 417 КБ инженерных записей
Прежний docs/mcp.md перенесён без изменений текста в
mcp-implementation-history.md с пометкой «исторический». Новый mcp.md
(19 КБ) написан по коду: настройка сервера, подключение клиента, путь
изменения, возможности, Route AI, webhook отзыва, восстановление базы,
ограничения и проверки. Инструкция по включению дополнена правом
mm:settings:admin и путём «Система» → «MCP»; входящие ссылки обновлены.

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

29 KiB
Raw Blame History

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

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

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

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

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

Это закреплено тестом на свежей базе (integration.test.ts). Подключений нет, пока администратор их не создаст.

Названия в кавычках «…» — надписи в интерфейсе, раздел «Система» → «MCP» в Manager. Общее описание MCP — mcp.md.

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

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

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

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

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

  • 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. Нажмите «Закрыть и скрыть токен».

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

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

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

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

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

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

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

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

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

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

Оба срока видны в строке подключения: «Доступ до» и «Права владельца до».

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

«Обновить мои права» аннулирует все неприменённые планы подключения и выключает его профили Route AI. Подтверждайте права до того, как агент начнёт готовить планы.

Если в портале отозвать сессии пользователя, 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 плана. Без подтверждения применение отклоняется с APPROVAL_REQUIRED. Администратор (mm:mcp:admin) может применить подтверждённый план и сам: «Применить план».
  5. Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через mm_operation_get.

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

  • 5 минут для операций раздела network в каталоге операций;
  • 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-привязка;
  • у каждого пути — контрольная проба с исходным адресом.

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

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

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

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

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

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

Действие Где Что происходит Обратимо
«Пауза» «Подключения» Токены подключения не принимаются, неприменённые планы аннулируются да, «Включить»
«Отозвать» «Подключения» Подключение и все его токены отозваны, неприменённые планы аннулируются нет: CONNECTION_REVOKED
«Новый токен» «Подключения» Старый токен перестаёт работать. OAuth-токены и временные допуски остаются —
«Отозвать допуск» «Проверка подключения и временные допуски» Временный допуск и его токен перестают действовать нет
Снять «Разрешить обращения 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 Аудит недоступен восстановить базу или аудит; изменения до этого не выполняются
APPROVAL_REQUIRED Применение плана без подтверждения человеком подтвердить план в «Планы и операции»
PLAN_EXPIRED Истёк срок плана или исходных данных подготовить новый план
CONFIGURATION_BUSY Глобальная конфигурация занята другой операцией дольше 30 секунд повторить позже

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

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

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