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. Bootstrap each machine and its SSH access once; after that, the nodes are fully managed from the agent itself through VantaMCPd's MCP interface. 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, Node setup, and MCP client integration for the currently supported combinations.

Modules

Modules extend managed nodes with MCP tools for useful workloads. VantaMCPd checks each module's declared hardware and software requirements. From the agent, you can use MCP to approve and install a module on compatible nodes, then invoke its tools according to the module's deployment policy.

Use cluster_list_modules to see packaged versions, install options, compatibility, deployment policies, and live installation state. See Node modules for architecture and lifecycle details.

Related MCP server: CommandBridge MCP

Test coverage

npm test builds the project and runs 117 automated tests covering schemas, security boundaries, artifact integrity, module packaging and lifecycle, SSH/MCP transport, jobs, routing, and the monitoring dashboard. The current end-to-end matrix also calls every installed module through its public MCP API, one operation and explicit node at a time; internal module self-tests are not counted as integration coverage.

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; see Node setup for the short first-boot checklist.

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 worker-a and worker-b, then install it there.

Check whether corpus-search is compatible with storage-a, install it using the Medium profile, then show its job progress.

Check whether browser-retrieval is compatible with browser-worker, install it there, and retrieve https://example.com/ as Markdown.

Install python-compute on worker-a with the science bundle, then ask it which Python packages the node provides.

Install image-processing on the ARM workers, then inspect an uploaded image artifact and create a metadata-free WebP thumbnail.

Module installation requires approval and explicit target nodes or tags. See Node modules for deployment, routing, durable jobs, and update behavior, the Text Tools quickstart for replicas and routing, and the Corpus Search quickstart for profiles, storage, installation, and recovery. See the Browser Retrieval quickstart for public network policy, rendered extraction, and service isolation, and the Python Compute quickstart for package bundles, sandbox behavior, and returning rendered content. The Image Processing quickstart covers raster formats, inline and artifact transport, ordered edit pipelines, and image-specific isolation.

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".

Cluster model

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

Physical topology

flowchart TB
    subgraph HOST["Vanta host · Windows or Linux"]
        direction LR
        AGENT["MCP-capable agent"]:::client -->|"MCP"| VANTA["VantaMCPd<br/>core tools + module router"]:::control
        INVENTORY[("Inventory<br/>hardware + roles")]:::config --> VANTA
        CATALOG[("Module catalog")]:::config --> VANTA
        KEY[("SSH key")]:::config --> VANTA
        VANTA --> MONITOR["Local monitor<br/>127.0.0.1:7420"]:::monitor
    end

    subgraph NODES["Managed Linux nodes"]
        direction LR
        N1["worker-a<br/>worker"]:::worker
        N2["worker-b<br/>worker"]:::worker
        N3["worker-c<br/>worker"]:::worker
        N4["storage-a<br/>worker + storage<br/>/srv/storage"]:::storage
    end

    VANTA -->|"SSH :22"| N1
    VANTA -->|"SSH :22"| N2
    VANTA -->|"SSH :22"| N3
    VANTA -->|"SSH :22"| N4
    N4 -.->|"NFS"| N1
    N4 -.->|"NFS"| N2
    N4 -.->|"NFS"| N3

    classDef client fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px
    classDef control fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:2px
    classDef config fill:#f3f4f6,stroke:#6b7280,color:#111827
    classDef monitor fill:#cffafe,stroke:#0891b2,color:#164e63
    classDef worker fill:#fef3c7,stroke:#d97706,color:#451a03
    classDef storage fill:#fee2e2,stroke:#dc2626,color:#450a0a,stroke-width:2px

Request and module flow

flowchart TB
    REQUEST["Agent request"]:::client --> VANTA["VantaMCPd"]:::control
    VANTA -->|"built-in cluster_* tool"| CORE["Core operation"]:::core
    CORE -->|"bounded SSH command"| TARGETS["Explicit node targets"]:::node

    VANTA -->|"module tool"| DISCOVER["Validate catalog<br/>and receipts"]:::module
    DISCOVER --> POLICY{"Deployment policy"}:::decision
    POLICY -->|"replicated"| REPLICA["Round-robin or<br/>explicit target"]:::module
    POLICY -->|"singleton"| SINGLE["Sole installation"]:::module
    REPLICA --> PROCESS["Node-side MCP process"]:::module
    SINGLE --> PROCESS

    TARGETS --> RESULT["Normalized result"]:::result
    PROCESS --> RESULT
    RESULT --> REQUEST

    classDef client fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px
    classDef control fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:2px
    classDef core fill:#cffafe,stroke:#0891b2,color:#164e63
    classDef node fill:#fef3c7,stroke:#d97706,color:#451a03
    classDef module fill:#ede9fe,stroke:#7c3aed,color:#2e1065
    classDef decision fill:#ffedd5,stroke:#ea580c,color:#431407
    classDef result fill:#f3f4f6,stroke:#6b7280,color:#111827

Core tools fan out over SSH with bounded concurrency and drive stock utilities such as apt, systemctl, journalctl, and lsblk. Module calls validate live installation receipts, apply the manifest's deployment policy, and launch the selected node-side MCP process over SSH stdio.

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. Prepare each managed machine with Node setup; platform support details and standalone SSH procedures remain in Host setup.

Operate the cluster

The built-in Core module provides the cluster management capabilities below. 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 worker-b

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 storage-a, 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

storage-a 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 worker-a

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.

Installed modules add workload-specific tools beyond these Core operations. See the module catalog for the available modules and Node modules for installation, routing, lifecycle, and usage details.

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.

• Jobs — active and recent durable operations with target, status, phase, progress, duration, and heartbeat freshness. The dashboard is read-only; cancellation remains a confirmed MCP operation.

• 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.

Clicking a node opens its access settings, installed modules, hardware, storage, filesystems, and operating-system details without exposing its configured address or key path.

Clicking an installed module opens its manifest details, compatibility requirements, installations, and live MCP tool API. Tool input schemas are available inline from the same dialog.

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 (["worker-a","storage-a"]), 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.