31 KiB
Включение MCP: наблюдение → подтверждения → ограниченная автономность
Инструкция для администратора Manager. Она описывает, как дать внешнему AI-клиенту доступ через MCP в три шага, с проверкой на каждом шаге:
- Наблюдение: агент только читает.
- Подтверждения: агент готовит изменения, человек одобряет каждое.
- Ограниченная автономность: агент применяет изменения сам, в узкой области и в пределах лимитов.
По умолчанию всё выключено. После установки:
- 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
- «Настройки» → «Настройки MCP» → включите «Разрешить обращения MCP».
- Там же задайте сроки хранения:
- «Хранение обращений, дней»: от 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». Он показывается один раз:
- Скопируйте токен в секреты AI-клиента.
- Нажмите «Закрыть и скрыть токен».
Токен действует до срока подключения. «Новый токен» выпускает замену, старый токен сразу перестаёт работать. OAuth-токены и временные допуски при этом остаются: если токен утёк, используйте «Отозвать».
Подключить клиента
Подходит любой MCP-клиент с транспортом Streamable HTTP. Настройки клиента:
- адрес:
MCP_PUBLIC_URL; - заголовок:
Authorization: Bearer <токен>.
Формат настроек зависит от клиента. Держите токен в переменной окружения, а не в файле настроек.
Вход через OAuth вместо токена:
- «Настройки» → «OAuth-клиенты»: зарегистрируйте клиента. В поле «Redirect URI, по одному на строку» укажите адреса точно.
- При запросе доступа владелец видит «Разрешение OAuth-доступа» и выбирает подключение.
- Клиент получает доступ ровно этого подключения, не шире.
Права владельца
Подключение действует, пока подтверждены права его владельца. Подтверждение длится до истечения токена портала, с которым владелец подтвердил права, но не дольше 24 часов. Обновление сессии в портале этот срок не продлевает. Права подтверждаются:
- при создании подключения;
- при сохранении окна «Изменить разрешения»;
- кнопкой «Обновить мои права».
Оба срока видны в строке подключения: «Доступ до» и «Права владельца до».
Когда срок прошёл, любой вызов получает UNAUTHORIZED (401): «Подключение недействительно или требуется подтверждение прав владельца». Права подтверждает только сам владелец.
«Обновить мои права» аннулирует все неприменённые планы подключения и выключает его профили Route AI. Подтверждайте права до того, как агент начнёт готовить планы.
Если в портале отозвать сессии пользователя, Manager отзывает и его подключения MCP вместе с токенами и временными допусками.
Сервисное подключение
В «Подключения» → «Выдать доступ» администратор 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 делается так же: сменить режим на «Наблюдатель».
Как проходит изменение
- Агент вызывает
*_plan. Manager читает роутер, строит план и проверяет политику. - План получает состояние
awaiting-approval. Он виден в «Планы и операции» → «Планы изменений», а на вкладке «Обзор» растёт счётчик «Ожидают подтверждения». - Человек с
mm:mcp:approveоткрывает план, проверяет изменения и нажимает «Подтвердить план» или «Отклонить». Подтверждение относится ровно к показанному плану. - Агент вызывает
mm_change_applyс ID плана. Без подтверждения применение отклоняется сAPPROVAL_REQUIRED. Администратор (mm:mcp:admin) может применить подтверждённый план и сам: «Применить план». - Ход записи — в «Выполнение операций»: «Записано намерение», «Применена», «Результат проверен». Агент читает то же через
mm_operation_get.
У плана есть срок:
- 5 минут для операций раздела
networkв каталоге операций; - 15 минут для остальных;
- для
servers.pollиrouting.community.switch— меньше, если раньше истекают данные, на которых построен план.
Истёкший план не применяется: «Срок плана истёк. Подготовьте новый план».
Переключение постоянного профиля Route AI подтверждает только владелец подключения.
Защита объектов
«Разрешения» → «Защищённые объекты» → «Добавить защиту». Варианты:
- «Запрет изменений» — любой план, который затрагивает объект, отклоняется с
PROTECTED_OBJECT. - «Подтверждение человеком» — такой план требует подтверждения в любом режиме, в том числе в автономном.
Защита не ограничивает чтение.
Ставьте защиту до перехода к шагу 3, в первую очередь:
- на интерфейсы и адреса, через которые Manager управляет роутером;
- на маршруты к нему.
«Проверка разрешений» на той же вкладке показывает решение политики для операции и объекта без выполнения.
Если результат не тот
«Планы и операции» → «Сверка и восстановление»:
- Укажите UUID операции и нажмите «Сверить состояние операции». Manager прочитает роутер.
- «Подготовить обратный план» создаёт отдельный план возврата. Он проходит те же проверки и подтверждение. Если объект после операции изменили извне, 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 плана завершения).