Skills through MCP

What an MCP skill is

A skill is a set of tools provided by an MCP server (Model Context Protocol). You do not write one for every task: use an existing server for Postgres, web fetching, or filesystem access and run it where its target is available.

Nythronix workers are network-isolated, able to reach only the control plane and LLM, while databases, logs, and services live on remote machines behind agents. The MCP server therefore runs on the machine as an agent subprocess, reached through the control plane:

worker (MCP client)
   │ HTTP JSON-RPC, one call = one request/response
   ▼
control plane  /api/agents/:id/mcp/:server/…   (relay, worker token, audit)
   │ over the agent's WebSocket connection
   ▼
agent on machine → MCP server on loopback → target (local database, files, service)

No inbound exposure is needed. The agent already maintains an outbound control plane connection, and the MCP server reaches its target using the machine’s network.

The worker’s own memory tools (remember / read_history) and approved shell execution (run_shell) stay inside the worker and do not use MCP. See Workers and channels.

Discovery and activation

The protection model is that the machine’s catalog limits the control plane. The control plane never sends a launch command to an agent, only a skill name and parameters. The machine owner maintains the name-to-command mapping in /etc/nythronix/mcp-catalog.json:

[
  {
    "name": "postgres",
    "port": 9912,
    "params": ["db_uri"],
    "read_only": true,
    "command": ["mcp-proxy", "--stateless", "--host", "127.0.0.1", "--port", "$PORT", "--",
                "postgres-mcp", "--access-mode", "restricted", "$db_uri"]
  }
]

In command, $PORT is replaced with the entry’s port, and $<param> with a declared parameter supplied by the control plane. A compromised or foreign control plane can enable only what the owner already placed in the catalog, following the same principle as local sudo limits.

The workflow:

On connection, the agent advertises its catalog (names, parameters, and read_only, but not commands) and its running servers.
In Admin → Agents, an administrator opens Skills, enables catalog entries, fills in parameters, and clicks Save. The control plane sends the desired set; the agent starts, stops, or restarts subprocesses to match it and saves the applied set locally, restoring skills after a machine reboot. Settings can be edited while an agent is offline and apply on reconnection. Changes are audited as admin.agent.mcp_config_set.
At startup, the worker queries the organization’s machines for servers and loads tools as <machine>__<server>__<tool>, for example nyx-db__postgres__execute_sql.

Machines without a catalog can still use the legacy /etc/nythronix/mcp-servers.json format containing full commands. Those entries start with the agent.

Presets and filters

A worker’s skills field (“skills, e.g. postgres; empty = all”) restricts which servers it loads. Enter skill server names separated by spaces or commas; glob patterns are supported and matching is case-insensitive. Empty, all, or * means all skills. A postgres preset loads only Postgres tools, reducing both model confusion and available privileges. You can also set a preset when creating a channel.

Approval and auditing of modifying tools

A tool runs without approval if its catalog server has read_only: true or the tool declares readOnlyHint. Everything else, including tools without an explicit annotation, produces an approval card with the skill and arguments. Rejected calls never reach the machine; the worker receives a not-executed response and revises its plan.

Many existing servers do not set readOnlyHint on every tool. A machine owner can declare an entire server read_only, such as Postgres in restricted mode, to avoid redundant approvals.

Every executed tool call is audited by the control plane as agent.mcp.call, including organization, initiator, machine, server, and tool, even for automatic read-only calls. Rejected calls appear only as chat.approval.decided.

Isolation

Separate processes. Each MCP server is an agent subprocess on loopback. Disabling the skill or losing the agent terminates the subprocess.
No root. Before launching, the agent drops subprocess privileges to nyx-worker, the same user used for worker commands. If the agent itself is not root, it does not perform this drop.
Restricted outbound network access. deploy/host/skills-egress.sh and its nyx-skills-egress.service systemd unit redirect port-443 connections from nyx-worker through a local SNI filter. Allowed domains pass; others are terminated. TLS stays end to end. The agent’s control plane connection and local targets, such as Postgres on 5432 or loopback, are unaffected.

ALLOW="example.com api.github.com" ./skills-egress.sh up
./skills-egress.sh status

For external services, deploy/docker/Dockerfile.skills-host provides a container with the agent, mcp-proxy, mcp-server-fetch, and an outbound filter. It enrolls as a separate skills-host machine, needs CAP_NET_ADMIN, and takes allowed domains from SKILLS_ALLOW.

Examples

Postgres. Install mcp-proxy and postgres-mcp on the database machine, add the example postgres catalog entry, and restart the agent. In administration, enable the skill, set db_uri with a read-only database account, and save. A worker with the postgres preset gets about nine tools (execute_sql, list_schemas, explain_query, analyze_db_health, and others), running SQL without approvals while every call remains audited.

Web. A fetch entry (mcp-proxy --stateless … -- mcp-server-fetch) on a skills host provides a page-fetching tool. Keep read_only: false and restrict domains with skills-egress.sh: allowed domains return content, while others fail even after operator approval.

Most MCP servers use stdio only. The mcp-proxy --stateless adapter turns them into HTTP services the control plane can proxy.