MCP for operators

What it is

nyx-mcp is an MCP server running on your workstation. It communicates with Claude Code, Claude Desktop, or any stdio-capable MCP client and exposes the same actions available in an operator’s terminal: find machines, open relay tunnels, connect over SSH or RDP, and run quick read-only checks.

It does not expand your permissions. It uses the same control server API, API token, role checks, and auditing as the dashboard. No inbound ports are needed anywhere; the target agent must be online.

Installation

1. Install the tools with one command. See Operator workstation for details, updates, accounts, and tokens.

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

2. Sign in with a nyxop_… token from Settings → API tokens. run_command and authorize_ssh_key require admin or owner.

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

   The token is saved to ~/.config/nythronix/operator.json with permissions 0600. NYX_SERVER and NYX_TOKEN can override the file.

3. Register the server in your client. For Claude Code, at user scope for all projects:

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

   For Claude Desktop, add the same command under mcpServers in its configuration.

4. To avoid manually approving every call, allow the server in ~/.claude/settings.json:

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

Logs go to stderr (RUST_LOG=debug for more detail); stdout is reserved for MCP transport.

Tools

Tool	Purpose
list_agents(query?, tags?, online_only?, os?)	List machines with presence, OS, version, and tags. query is a substring of name, hostname, login, or tag; all tags must match; os accepts linux, windows, or windows7.
get_agent(agent)	Find a machine by ID, name, hostname, or login, case-insensitively. A unique substring is enough; if multiple records match and exactly one is online, choose it. Offline results include last_seen_at and the last known OS and version.
open_tunnel(agent, port=22, idle_minutes=30)	Local TCP port → control server relay → machine loopback port. Any port works: 22 for SSH/scp, 3389 for RDP, 5432 for Postgres, or a web port. usage returns a suitable command or URL; note includes caveats. Repeated calls for the same agent/port return the existing tunnel. Requires an online machine with Relay enabled.
list_tunnels()	List open tunnels: local port, machine, remote port, and activity.
close_tunnel(local_port)	Close one tunnel.
close_all_tunnels()	Close every tunnel in this session.
set_tags(agent, tags)	Replace machine tags (client:acme, role:kassa, env:prod).
authorize_ssh_key(agent, public_key?, user?, repair_sshd_config?)	Install your public key through the agent, defaulting to ~/.ssh/id_ed25519.pub. Linux requires user; Windows uses administrators_authorized_keys. Idempotent, admin-only, and audited. On Windows, also checks that sshd will actually read the key; see below.
run_command(agent, command, timeout_secs?)	Run a command through the control server. timeout_secs defaults to 120, maximum 600. Returns stdout, stderr, and exit_code.

Expected refusals, such as offline machines, ambiguous names, or prohibited commands, return tool results marked as errors with next-step hints, not protocol failures.

Why this is safe

run_command permits only recognized read-only commands and chains or pipelines made entirely from them. Linux examples include df, ps, cat, and systemctl status. Windows examples include ver, systeminfo, tasklist, dir, type, sc query, reg query, wmic … get, ipconfig, netsh … show, ping, tracert, nslookup, and powershell -Command Get-*. The control server gateway makes the decision, so the client cannot bypass it.

Refusals identify the offending segment instead of giving a generic approval-required message, for example segment 2 "del x" is state-changing, leaving the rest of the chain unchallenged.

Caution

Changes to the machine are performed over SSH through a tunnel, under your own machine credentials rather than the platform’s identity. Each run_command is audited as agent.cmd_exec; key installation as admin.agent.ssh_key_authorized, recording only key type and comment.

Note

Output is returned as UTF-8 regardless of console code page, but stays in the machine’s language: a Russian Windows installation prints the Russian label for OS name, not OS Name.

The Windows key is installed, but login fails

Writing administrators_authorized_keys is only half the job. Two conditions make sshd silently ignore a file containing the correct key:

• Unexpected file permissions. sshd rejects the key file if anyone other than Administrators and SYSTEM can read it. A single Authenticated Users entry is enough. The agent now resets permissions to exactly those two entries.
• A localized Match Group line in sshd_config. sshd reads this file through the Match Group administrators block and matches the group by its system identifier, so the English name is correct in every locale. A manually translated group name is parsed as a different group and the key file is never opened.

authorize_ssh_key checks both conditions and returns an error instead of success if either fails. Details appear in acl_ok, acl_unexpected, sshd_config_ok, and sshd_config_note.

repair_sshd_config=true allows the agent to rewrite Match Group and restart sshd. The original configuration is backed up beside it as sshd_config.nythronix.bak. The option is off by default because it changes machine configuration and restarts a service. The Windows installer performs the same check on every installation.

Older Windows systems

Machines with os=windows7 are handled separately. This marks the legacy agent build for Windows 7, 8, and 8.1, and Server 2008 R2 through 2012 R2. They have no dashboard terminal, use PowerShell 2.0, and get sshd from the installer. run_command refusals and tunnel hints suggest available tools such as wmic and Get-WmiObject, instead of commands introduced in Windows 8 or later. See Windows installation.

Tunnels

Tunnels live inside the nyx-mcp process. Each connection updates activity; a tunnel closes after idle_minutes without connections (default 30). Increase the value for long tasks. When the MCP client exits, the process and its tunnels terminate, leaving no listening ports.

Example

list_agents(query="checkout", online_only=true)
  → checkout-2, windows, online, tags client:acme role:kassa
authorize_ssh_key(agent="checkout-2")
  → key installed; log in as any local administrator
open_tunnel(agent="checkout-2", port=22)
  → 127.0.0.1:49711 → checkout-2:22

Continue with ordinary tunnel access:

ssh -p 49711 Administrator@127.0.0.1

Or run a quick check without logging into the machine:

run_command(agent="checkout-2", command="sc query NythronixAgent")

Next steps

• Operator workstation: installation, updates, accounts, and roles.
• SSH relay and tunnels: relay internals and server visibility.
• CLI reference: nyx-operator and its subcommands.
• Machines: presence, tags, and enabling relay.