MCP для операторов

Что это

nyx-mcp — MCP-сервер, который вы запускаете на своей рабочей машине. Он говорит с MCP-клиентом (Claude Code, Claude Desktop и любой другой клиент, умеющий stdio) и даёт ему тот же набор действий, который у оператора есть в терминале: найти машину, открыть реле-туннель, зайти по SSH или RDP, выполнить быструю проверку только на чтение.

Сервер не расширяет ваши права. Он ходит в тот же API сервера управления, что и кабинет, под тем же API-токеном, с теми же проверками роли и той же записью в аудит. Входящие порты не нужны нигде: достаточно, чтобы агент на машине был online.

Установка

1. Поставьте инструменты одной командой. Как это устроено, как обновляться и откуда взять учётную запись и токен, описано в разделе Рабочее место оператора.

   curl -fsSL https://nx.3fe.ru/downloads/install-operator.sh | bash

2. Войдите токеном nyxop_…, выпущенным в кабинете в «Настройки → API-токены». Для run_command и authorize_ssh_key нужна роль admin или owner.

   nyx-operator login --server https://app.nx.3fe.ru --token nyxop_…

   Токен ложится в ~/.config/nythronix/operator.json с правами 0600. Вместо файла можно задать переменные окружения NYX_SERVER и NYX_TOKEN, они имеют приоритет.

3. Зарегистрируйте сервер в клиенте. Для Claude Code — на уровне пользователя, для всех проектов:

   claude mcp add nythronix -s user -- ~/.local/bin/nyx-mcp

   Для Claude Desktop добавьте ту же команду в раздел mcpServers его конфигурации.

4. Чтобы не подтверждать каждый вызов вручную, разрешите сервер в ~/.claude/settings.json:

   { "permissions": { "allow": ["mcp__nythronix"] } }

Логи идут в stderr (RUST_LOG=debug — подробнее), stdout занят транспортом MCP.

Инструменты

Инструмент	Что делает
list_agents(query?, tags?, online_only?, os?)	список машин с присутствием, ОС, версией и тегами. query — подстрока по имени, hostname, логину или тегу; tags — должны совпасть все; os — linux, windows, windows7
get_agent(agent)	одна машина по ID, имени, hostname или логину (без учёта регистра, хватает уникальной подстроки; если подходит несколько, а online ровно одна — выбирается она). Для offline-машин возвращается last_seen_at и последние известные ОС и версия
open_tunnel(agent, port=22, idle_minutes=30)	локальный TCP-порт → реле сервера управления → порт на loopback машины. Порт любой: 22 для ssh и scp, 3389 для RDP, 5432 для Postgres, веб-порт для браузера. В ответе поле usage содержит готовую команду или адрес для этого порта, а note — оговорки. Повторный вызов для той же пары агент+порт возвращает уже открытый туннель. Требует, чтобы машина была online и у неё было включено «Реле»
list_tunnels()	открытые туннели: локальный порт, машина, удалённый порт, активность
close_tunnel(local_port)	закрыть один туннель
close_all_tunnels()	закрыть все туннели этой сессии
set_tags(agent, tags)	заменить набор тегов машины (client:acme, role:kassa, env:prod)
authorize_ssh_key(agent, public_key?, user?, repair_sshd_config?)	положить ваш публичный ключ на машину через агента. По умолчанию берётся ~/.ssh/id_ed25519.pub. На Linux параметр user обязателен, на Windows ключ уходит в administrators_authorized_keys. Идемпотентно, требует роли admin, пишется в аудит. На Windows дополнительно проверяет, что sshd действительно прочитает ключ, см. ниже
run_command(agent, command, timeout_secs?)	команда на машине через сервер управления. timeout_secs — по умолчанию 120, максимум 600. Возвращает stdout, stderr, exit_code

Ожидаемые отказы — машина offline, неоднозначное имя, запрещённая команда — приходят как результат вызова с признаком ошибки и подсказкой, что делать дальше, а не как сбой протокола.

Почему это безопасно

run_command выполняет только команды, которые распознаны как читающие, и цепочки или конвейеры целиком из таких команд: на Linux — df, ps, cat, systemctl status и подобные, на Windows — ver, systeminfo, tasklist, dir, type, sc query, reg query, wmic … get, ipconfig, netsh … show, ping, tracert, nslookup, powershell -Command Get-*. Решение принимает не MCP-сервер, а шлюз сервера управления, поэтому обойти его со стороны клиента нельзя.

Отказ называет виновный фрагмент, а не отвечает общим «требуется подтверждение»: например, segment 2 "del x" is state-changing — остальная часть цепочки претензий не вызывает.

Осторожно

Всё, что меняет машину, делается по SSH через туннель — то есть под вашими собственными учётными данными на машине, а не от имени платформы. Каждый вызов run_command пишется в аудит как agent.cmd_exec, установка ключа — как admin.agent.ssh_key_authorized (только тип ключа и комментарий).

Заметка

Вывод возвращается в UTF-8 при любой кодовой странице консоли, но остаётся на языке машины: русская Windows напечатает «Название ОС», а не OS Name.

Ключ на Windows установлен, а вход не работает

Положить ключ в administrators_authorized_keys это половина дела, и вторая половина ломается молча. Две вещи заставляют sshd полностью игнорировать файл с правильным ключом:

• Лишняя запись в правах на файл. sshd отказывается читать файл ключей, если его может прочитать кто-то кроме администраторов и системы. Достаточно одной записи для «Прошедших проверку». Агент теперь сбрасывает права и выставляет заново ровно две записи.
• Локализованная строка Match Group в sshd_config. sshd читает этот файл только из-за блока Match Group administrators и сопоставляет группу по системному идентификатору, так что английское слово верно в любой локали. Конфиг, где руками написано Match Group администраторы, разбирается как другая группа, и файл ключей не открывается никогда.

authorize_ssh_key проверяет оба условия и возвращает ошибку, а не успех, если хотя бы одно нарушено. В ответе видно, что именно не так: поля acl_ok, acl_unexpected, sshd_config_ok, sshd_config_note.

Параметр repair_sshd_config=true разрешает агенту переписать блок Match Group и перезапустить sshd. Прежний конфиг сохраняется рядом как sshd_config.nythronix.bak. По умолчанию параметр выключен, потому что это правка конфигурации машины и перезапуск службы. Установщик Windows делает ту же проверку при каждой установке.

Старые Windows

Машины с os=windows7 учитываются отдельно. Так помечена старая сборка агента, которая работает на Windows 7, 8 и 8.1 и на Server от 2008 R2 до 2012 R2: у них нет терминала в кабинете, стоит PowerShell 2.0, а sshd берётся из установщика. Отказы run_command и подсказки к туннелям называют то, что там действительно есть, wmic и Get-WmiObject, а не команды из Windows 8 и новее. Что работает на каких системах, см. в разделе Установка на Windows.

Туннели

Туннели живут внутри процесса nyx-mcp. Каждое соединение обновляет счётчик активности; если соединений нет idle_minutes подряд (по умолчанию 30), туннель закрывается сам. Для долгой работы передайте значение больше. Когда MCP-клиент завершается, процесс умирает вместе со всеми туннелями — ничего не остаётся слушать порт.

Пример

list_agents(query="касса", online_only=true)
  → касса-2, windows, online, теги client:acme role:kassa
authorize_ssh_key(agent="касса-2")
  → ключ установлен, входить можно любым локальным администратором
open_tunnel(agent="касса-2", port=22)
  → 127.0.0.1:49711 → касса-2:22

Дальше — обычная работа через туннель:

ssh -p 49711 Администратор@127.0.0.1

А быструю проверку удобнее сделать не заходя на машину:

run_command(agent="касса-2", command="sc query NythronixAgent")

Дальше

• Рабочее место оператора — установка, обновление, учётная запись и роли.
• SSH-реле и туннели — как устроено реле и что видит сервер.
• Справочник CLI — nyx-operator и его подкоманды.
• Машины — присутствие, теги и включение реле.