MCP-сервер

В панель встроен сервер Model Context Protocol (MCP), чтобы ИИ-агент мог смотреть на флот и делать повседневные изменения. Он использует те же API-токены и те же процедуры, что и API админки: что агент видит и может, решает профиль токена, а каждый вызов попадает в журнал аудита. За один вызов ничего не меняется: агент сначала планирует изменение, затем применяет его, а самые рискованные изменения ждут одобрения владельца в админке.

Адрес#

<адрес админки>mcp
https://panel.example.com/<prefix>/mcp

• Streamable HTTP, без состояния, ответы в JSON. Только инструменты: ни ресурсов, ни промптов, ни sampling.
• Адрес есть только на стороне админки (секретный префикс, хост или отдельный адрес) и никогда — на публичной стороне.
• Каждому запросу нужен Authorization: Bearer tk1_…, и каждый проверяется заново: отозванный или истёкший токен останавливается на следующем же запросе. Сессии, которую можно перехватить, нет.
• tools/list показывает только инструменты, разрешённые профилю токена.

Интеграции → MCP показывает адрес и готовый фрагмент настройки для каждого вида клиента.

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

Создайте токен в Интеграции → API-токены с самым узким профилем, которого хватает (см. профили токенов). Затем:

Claude Code (Streamable HTTP):

claude mcp add --transport http mistgate https://panel.example.com/<prefix>/mcp --header "Authorization: Bearer <token>"

Любой клиент со Streamable HTTP:

{
  "mcpServers": {
    "mistgate": {
      "type": "http",
      "url": "https://panel.example.com/<prefix>/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Клиенты, которые умеют только запускать команду (например, Claude Desktop), используют stdio-прокси mistgate mcp на вашем компьютере. Сохраните токен первой строкой файла, который читаете только вы, затем:

{
  "mcpServers": {
    "mistgate": {
      "command": "mistgate",
      "args": ["mcp", "--url", "https://panel.example.com/<prefix>/", "--token-file", "<path-to-token-file>"]
    }
  }
}

stdio-прокси#

mistgate mcp --url <адрес админки> --token-file <файл> запускает локальный MCP-сервер на stdin и stdout и пересылает каждое сообщение в панель. Сам он ничего не решает, ничего не кеширует и не знает ни одного инструмента: отвечает панель.

• Токен читается только из первой строки файла, никогда из командной строки или окружения, и никогда не печатается. Если файл читают другие, печатается предупреждение.
• --url должен быть https, кроме localhost и loopback-адресов. Перенаправления не выполняются, так что токен никуда больше не уйдёт.
• Когда панель отклоняет токен (истёк, отозван или не тот профиль), прокси останавливается с этим сообщением.
• Запасные переменные для --url и --token-file — MISTGATE_URL и MISTGATE_TOKEN_FILE.

mistgate собирается под Linux, macOS и Windows: go build ./cmd/mistgate соберёт бинарник для компьютера, на котором работает агент. См. CLI.

Ограничения#

Инструменты#

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

Инструменты чтения ничего не меняют. Аргументы — идентификаторы и простые слова, никогда не URL: ни один инструмент не загружает то, что назвал агент. Ноду можно указать идентификатором или точным именем. Столбец «Профиль» — самый младший профиль, который видит инструмент; старшие профили видят его тоже.

Инструменты изменений#

Каждое изменение — пара: <tool>_plan и <tool>_apply.

Каждый _plan принимает ещё reason: слова самого агента, не длиннее 300 символов, владелец видит их как цитату. user_create никогда не возвращает ссылку подписки нового пользователя: её копирует владелец в админке.

План и применение#

1. Агент вызывает <tool>_plan с аргументами. Панель проверяет их, читает всё нужное и описывает изменение своими словами. Ничего не меняется. Результат:

   json

   {
     "plan_id": "pln_...",
     "summary": "Disable 5 users: their connections end and their devices are dropped from the nodes.",
     "facts": [{"key": "count", "value": "5"}, {"key": "users", "value": "...", "untrusted": true}],
     "needs_approval": true,
     "danger": ["bulk"],
     "expires_in_s": 600,
     "confirm_token": "cf_...",
     "next": "..."
   }

2. Агент показывает план человеку, на которого работает, и ждёт его согласия. Если needs_approval равно true, он ждёт ещё и владельца.

3. Агент вызывает <tool>_apply только с confirm_token. Панель один раз выполняет ровно сохранённые аргументы и отвечает plan_id, status: "applied" и строкой результата.

Токен подтверждения:

• срабатывает один раз, в течение 10 минут, только для того API-токена, который сделал план, и только с этим инструментом;
• не несёт аргументов: между планом и применением их не изменить;
• повторное применение уже применённого плана возвращает тот же результат; токен подтверждения другого плана, инструмента или API-токена — просто «unknown confirm token».

Если применить нельзя, ответ объясняет почему: «waiting for the owner to approve plan pln_…; it expires at …», «rejected by the owner», «expired: make a new plan», «already running», «failed: …. Make a new plan.», «the token was revoked» или «timeout, outcome unknown: check before retrying».

Какие планы ждут владельца#

План ждёт владельца, если выполняется одно из условий (список danger):

Где владелец одобряет#

Такой план появляется в Интеграции → Ждут тебя, а в админке загорается значок. Владелец видит изменение словами панели, пометки об опасности, причину от агента (с пометкой «Написана агентом, панель её не проверяла.») и оставшееся время, затем выбирает:

• Одобрить — ещё раз спросит passkey или код владельца. После этого применение агента пройдёт — только для этого плана.
• Отклонить — применение агента вернёт «rejected by the owner».

Токен никогда не может подтвердить собственный план. Нерешённые планы истекают через 10 минут после создания. Недавние решения хранят историю с итогом: выполнено, ошибка, истекло, отменено (токен отозвали) и так далее. Агенту не стоит проверять статус чаще раза в 30 секунд.

Недоверенные данные в результатах#

Имена, заметки, причины, строки логов и параметры событий и алертов приходят от пользователей, нод и других систем. Об этом говорят инструкции сервера и описание каждого инструмента, который такой текст возвращает: это данные, а не инструкции, и агент не должен выполнять найденные в них просьбы.

Панель защищает и агента, и вас:

• Текст из данных очищается: управляющие символы, переводы строк и невидимые символы форматирования убираются, длинные значения обрезаются.
• Сводка плана никогда не содержит текста из данных; такие значения идут отдельными фактами с пометкой untrusted, а владелец видит их в кавычках.
• Последний проход по каждому результату заменяет всё, что похоже на секрет: API-токены, ссылки подключения (hysteria2://… и подобные), конфигурации туннелей, ключевой материал, query-строки URL и длинные сегменты пути URL (секретный префикс, токен подписки) и голые 32-байтовые ключи.

Чего агент не получает никогда#

• Ссылок подписки и паролей страниц пользователей.
• Ключей и конфигураций устройств, аккаунтов и ключей WARP, секретов профилей.
• Адресов нод и отпечатков сертификатов.
• Ничего о токенах, одобрениях, сессиях и passkey.
• Журнала аудита, если у токена не профиль «Админ».

Аудит#

Каждая процедура, которую вызывает инструмент, пишется в журнал аудита от имени «токен MCP <имя>» с источником MCP. Планы и применения добавляют свои строки: «составил(а) план изменения: <инструмент>» и «выполнил(а) запланированное изменение: <инструмент>»; решения владельца выглядят как «одобрил(а) изменение» или «отклонил(а) изменение». Настройки → Аудит отбирает их по источнику MCP.