VantaMCPd

Put old hardware back to work. Give your agent a cluster.

Vanta is the quiet layer beneath the work: it absorbs the awkward differences between machines, operating systems, remote access, and runtimes, then presents the useful signal as one MCP interface. Complexity is not something to hide from; it is raw material to turn into capability.

VantaMCPd lets agents operate a heterogeneous cluster of Linux nodes over SSH. Bootstrap secure access once, then inspect status and logs, manage packages, services, files, storage, and NFS, or install node-side MCP modules that add new capabilities quickly. Small ARM boards can do useful work today, while x86 and accelerator-equipped nodes fit the same model with more advanced capabilities.

The project ships no real hosts. The cluster is described by a local inventory file you create from a template; everything else, including tools, scripts, and docs, is written against roles, not specific machines.

Three parts are deliberately independent:

With stdio MCP, the agent launches VantaMCPd on its own host. The agent and Vanta host are therefore usually the same machine, but they are different roles in the architecture. See Host setup and MCP client integration for the currently supported combinations.

QuickStart

From a clean checkout to a working agent-driven cluster. Run steps 1-5 on the Vanta host, then complete step 6 in any MCP-capable agent. Node.js 20.11 or newer, npm, and an OpenSSH client are required. Choose either host path below: Linux uses standard Node.js and SSH tools, while Windows provides PowerShell helpers for the same setup. Git is needed only to clone or update the checkout.

1. Install host prerequisites and build.

Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\install-prereqs.ps1

Linux, after installing Node.js 20.11+, npm, and openssh-client with your distribution's package manager or the Node.js downloads:

node --version
ssh -V
npm install
npm run build

2. Create and edit the inventory.

# PowerShell
if (-not (Test-Path .\cluster.config.local.json)) {
  Copy-Item .\cluster.config.example.json .\cluster.config.local.json
}

# Bash
test -e cluster.config.local.json || cp cluster.config.example.json cluster.config.local.json

Set the real node names, addresses, user, roles, and storage in cluster.config.local.json. The managed nodes must already run Debian/Armbian with SSH and a sudo-capable account.

3. Bootstrap key authentication and passwordless sudo on each node.

# Windows helper: prompts for each node's login and sudo password once
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1

On Linux, use ssh-keygen, ssh-copy-id, and visudo as shown in Linux node enrollment. This is a one-time operation; passwords go directly to SSH and sudo, never through VantaMCPd or the agent.

4. Install the baseline packages on the managed nodes.

# Windows helper
powershell -ExecutionPolicy Bypass -File .\scripts\prepare-nodes.ps1

Linux hosts can use the equivalent SSH command in Host setup.

5. Register VantaMCPd with the agent.

Every client launches the same local stdio process:

command: node
args:    ["<absolute-repo-path>/dist/index.js"]
env:     { "VANTA_CONFIG": "<absolute-repo-path>/cluster.config.local.json" }

The repository already includes .vscode/mcp.json for VS Code. Exact configurations for Claude Code, Hermes Agent, OpenClaw, and generic MCP clients are in MCP clients.

6. Discover and install node modules from your agent:

List the available node modules and their deployment policies.

Check whether text-tools is compatible with cluster1 and cluster2.

Install text-tools on cluster1 and cluster2.

The install prompt requires your approval before VantaMCPd calls cluster_install_module with confirm: true. Installations always use explicit node names or tags; they never default to the entire cluster. Replicated modules such as Text Tools may be installed on multiple compatible nodes, while singleton modules reject a second installation.

At daemon startup, validated module receipts are compared with the local catalog. Installed older versions are upgraded automatically after hardware discovery; absent modules are not installed and newer node versions are not downgraded. Set defaults.autoUpdateModules to false to opt out.

Re-running the whole block on a working cluster is safe. Every step is idempotent: an existing SSH key is reused, authorized_keys and /etc/sudoers.d/99-vanta are left alone once correct (so you are not even prompted for a password), and already-present packages are not upgraded. Module activation may install apt packages declared by that module after confirmation. On Windows, step 3 also re-probes the nodes and refreshes the hardware blocks. Step 2 guards the private inventory with Test-Path or test -e, so an existing cluster configuration is not overwritten; bootstrap.ps1 applies the same guard itself if you skip step 2 entirely.

Windows helper checks — these change nothing on the Vanta host or managed nodes:

.\scripts\install-prereqs.ps1 -Check     # Windows Vanta host
.\scripts\bootstrap.ps1      -Verify     # key + sudo state per node
.\scripts\prepare-nodes.ps1  -Check      # packages per node

Keeping the inventory current as the cluster changes:

npm run discover re-probes the nodes and writes the refreshed hardware blocks back to the inventory; your diskRoles overrides are preserved. Since the inventory is gitignored and holds the only record of your cluster, back it up before large changes:

cp cluster.config.local.json "cluster.config.local.json.bak-$(date +%Y%m%d%H%M%S)"

PowerShell users can use Copy-Item instead.

Then ask your agent: "Check the status of all cluster nodes".

Related MCP server: CommandBridge MCP

Cluster model

So targets: ["storage"] hits every storage node and targets: ["worker"] every worker, on any cluster, without hard-coding names.

flowchart LR
    subgraph HOST["Vanta host · Windows or Linux"]
        direction TB
        AGENT["MCP-capable agent<br/>Copilot · Claude · Hermes · OpenClaw"]
      MCP["vantamcpd<br/>built-in tools · module lifecycle + routing"]
        INV[("cluster.config.local.json<br/>inventory + hardware")]
      CAT[("trusted module catalog<br/>replicated · singleton")]
        KEY[("~/.ssh/vanta_cluster_ed25519")]
        AGENT <-->|"MCP tool calls"| MCP
        MCP --- INV
      MCP --- CAT
        MCP --- KEY
    end

    subgraph LAN["Cluster LAN"]
        direction TB
      W1["cluster1 · <b>worker</b><br/>SD card: system<br/>USB stick: swap<br/>optional: text-tools replica"]
      W2["cluster2 · <b>worker</b><br/>SD card: system<br/>USB stick: swap<br/>optional: text-tools replica"]
        W3["cluster3 · <b>worker</b><br/>SD card: system<br/>USB stick: swap"]
        S1["cluster4 · <b>worker+storage</b><br/>SD card: system<br/>USB stick: swap<br/>SSD: /mnt/ssd"]
        S1 -->|"NFS export of /mnt/ssd"| W1
        S1 --> W2
        S1 --> W3
    end

    MCP -->|"SSH :22 · built-in commands + module MCP stdio"| W1
    MCP --> W2
    MCP --> W3
    MCP --> S1

Every operation starts on the same path: the agent calls an MCP tool and the daemon resolves explicit targets against the inventory or routes a targetless module call according to its manifest. Built-in cluster tools fan out over SSH with bounded concurrency and drive stock apt, systemctl, journalctl, lsblk and friends. Optional modules are installed on compatible nodes, then launched through SSH stdio on demand or managed as systemd services according to their runtime policy.

Inventory files:

Set VANTA_CONFIG when the daemon should load an inventory from a different path.

Installation

The QuickStart above covers the shortest path to a working cluster. For the complete six-step Windows and Linux walkthrough, including managed-node preparation, enrollment checks, and command variants, see Installation. Platform support details and standalone SSH procedures remain in Host setup.

Operate the cluster

Once connected, ask the agent:

Health and triage

Check the status of all cluster nodes

Which node has the least free disk space, and what is using it?

Are any systemd units failed anywhere in the cluster?

Show me the CPU temperature and load of every node - is anything throttling?

Has any node rebooted recently, or is a reboot pending?

Show the last 50 ssh journal errors on cluster2

Check dmesg on all nodes for USB or SD-card I/O errors

Inventory and hardware

List the cluster nodes with their roles and recorded hardware

Where can I watch what you are doing on the cluster?

Re-probe the hardware on cluster4, I swapped a disk

Which disks are unassigned, and what do you think they are for?

How much swap does each node have, and is it persistent across reboots?

Packages and services

Which nodes have pending apt upgrades?

Do a dry run of upgrading all nodes, then tell me what would change

Install htop and tmux on the workers only

Is nfs-kernel-server running on the storage node? Restart it if not

Disable the unattended-upgrades timer on all nodes and explain the trade-off

Storage and swap

Mount the SSD on the storage node and share it to the rest of the cluster over NFS

Is the NFS share mounted and writable on every worker?

Point apt's cache at the shared SSD so the nodes stop re-downloading the same packages

cluster4 lost its swap after a reboot - find out why and fix it

Files and config

Show me /etc/fstab on every node side by side

Back up /etc/exports from the storage node to my machine

Add a 2GB swap file on the shared SSD for cluster1

Destructive work (formatting, partitioning, reboots, rm -rf) is refused until you approve it explicitly, so it is safe to ask for it and then read back what the agent proposes.

Monitoring

The daemon records every SSH interaction and serves a live dashboard at http://127.0.0.1:7420.

Multiple launches: Each stdio client starts its own VantaMCPd process, and only one process can bind the default dashboard port 7420. Use a different monitoring.port in each client's inventory, or disable web monitoring for all but one process. See Multiple clients.

• Nodes — every configured node, installed-module count, calls, failures, timing, bytes moved, last tool and last activity. Click a row for configuration, module IDs and recorded hardware.

• Modules — active module versions, node coverage, deployment, runtime and package size. Click a row for manifest details and the live MCP tool API.

• Interactions — a tail-following list of every command, attributed to its module and the MCP tool that issued it, with redacted input parameters, exit status and duration. New rows appear live over SSE; following pauses it, and copy log path copies today's persisted JSONL file:// URL.

• Filters — by node, module, status (ok, exit 1, exit 4, error … built from what actually happened), and a free-text search across command, module, tool, parameters and error. They combine.

It binds to loopback only and there is deliberately no setting to change that: the log contains your hostnames, usernames and full command lines. Events are also appended to ~/.vanta/logs/vanta-<date>.jsonl for grepping after the fact. The daemon tells the agent the URL, so you can just ask "where can I watch this?". See Monitoring for the fields, retention and redaction behaviour.

Tools

The table below lists the built-in VantaMCPd tools. Each installed node module can add its own tools; discover them with cluster_list_module_tools and invoke them through cluster_call_module_tool. See Node modules for the current module catalog and tool guides.

targets accepts node names (["cluster1","cluster4"]), roles/tags (["storage"], ["worker"]), or is omitted / ["all"] to hit every node. Commands fan out with bounded concurrency (default 4).

Documentation

Operational details beyond getting started live in docs/Reference.md. Node-side module usage, architecture, implemented packages, and the roadmap are documented in docs/Modules.md.