# Включение MCP: наблюдение → подтверждения → ограниченная автономность Инструкция для администратора Manager. Она описывает, как дать внешнему AI-клиенту доступ через MCP в три шага, с проверкой на каждом шаге: 1. Наблюдение: агент только читает. 2. Подтверждения: агент готовит изменения, человек одобряет каждое. 3. Ограниченная автономность: агент применяет изменения сам, в узкой области и в пределах лимитов. **По умолчанию всё выключено.** После установки: - MCP выключен; - профили Route AI выключены; - автоматическое восстановление маршрутов выключено. Это закреплено тестом на свежей базе (`integration.test.ts`). Подключений нет, пока администратор их не создаст. Названия в кавычках «…» — надписи в интерфейсе, раздел «Система» → «MCP» в Manager. Общее описание MCP — [mcp.md](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 вместе с токенами и временными допусками. ### Сервисное подключение В «Подключения» → «Выдать доступ» администратор 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](mcp-final-manifest.md). - **Режим «С подтверждением» проверен на стенде.** - IPsec: пять прогонов подряд, в каждом 4 подтверждения в интерфейсе. Применение без подтверждения отклонено. - Маршрутизация A3: 2 подтверждения. - Выдача токена в интерфейсе, подтверждение плана и подписанный отзыв в настоящих Manager и Portal — EXT-1. - **Режимы «Наблюдатель» и «Автономный», защиты, бюджет и лимиты** покрыты тестами политики (`policy.test.ts`). В документах стенда доказательств их отдельной проверки нет. - **Сама инструкция** сверена с кодом: надписи — с `components/mcp/*.tsx`, числа и коды — с backend и контрактами. По интерфейсу её целиком не проходили. - **Раздел MCP в интерфейсе** проверен частично: выдача ограниченного доступа, отказы, фильтры и пагинация на стенде не проверялись (UI-1). - **Автоматическое восстановление маршрутов** не реализовано и выключено (этап 4 плана завершения).