Whatbox MCP

A security-first Model Context Protocol server that gives AI agents bounded, structured access to an owner-authorized Whatbox slot.

Whatbox MCP can inspect storage, directories, supported services, torrent-client process state, directory topology, configuration metadata, website-hosting readiness, and bounded userland Nginx diagnostics. It also validates local static-site sources and creates signed, short-lived deployment-plan previews.

As of 0.10.0 it can additionally perform approval-gated mutations — upload, download, move, mkdir, quarantine-based delete and second-approval purge, configuration backup, service start/stop/restart, atomic website deployment with rollback, and torrent add/control/remove over an SSH loopback tunnel. Mutations are disabled by default and every destructive action requires explicit human approval through the MCP protocol, even when an agent runs unattended.

The server runs locally over MCP stdio. Credentials remain outside the repository and are never accepted as tool arguments.

This is an independent project and is not affiliated with or endorsed by Whatbox.

Why this project exists

AI agents are useful for operating infrastructure only when their authority is clear and mechanically enforced. This server is designed around four rules:

1. prefer structured read-only observation;

2. expose narrow operations instead of a generic shell;

3. keep credentials and private configuration outside the model context;

4. require exact, short-lived external human approval before any future mutation.

Related MCP server: vps-ops-mcp

Current release

Version 0.10.0 includes everything from the read-only line —

• a local MCP stdio server for Node.js 20+;

• pinned SSH host verification and SSH-agent authentication;

• bounded, path-contained SFTP discovery;

• fixed read-only remote queries with bounded output;

• structured output schemas and readable titles for every tool;

• a consolidated agent-oriented operational snapshot;

• MCP operations-guide and tools-catalog resources and a safe-audit prompt;

• fixed Nginx syntax testing, an optional body-free loopback probe, and content-free recent-error severity counts;

• static-site source validation and signed deployment-plan previews;

— plus approval-gated mutations:

• a master WHATBOX_MUTATIONS_ENABLED kill-switch (off by default);

• HMAC-signed immutable plans carried as MCP requestState, with expiry, exact-target binding, and one-time consumption;

• destructive actions gated behind MCP elicitation (human approval), with a redacted local audit log of every planned, approved, denied, and executed step;

• file upload / download / move / mkdir with no-overwrite and free-space checks;

• quarantine-based delete and a separate second-approval permanent purge;

• allowlisted service configuration backup;

• fixed service start/stop/restart using the documented userland recipes;

• atomic static-site deployment with remote checksum verification, health check, and rollback;

• torrent add / pause / resume / label / ratio / remove over an SSH loopback tunnel to Transmission or qBittorrent;

• a credential-free test suite (53 tests), successful production build, and zero known npm audit vulnerabilities at the latest validation.

Install

Read the complete Installation Guide.

Quick source installation:

git clone https://github.com/SNSEIxAUGMNTD/whatbox-mcp.git
cd whatbox-mcp
npm ci
npm run typecheck
npm test
npm run build

The project is not documented as npm-installable until an npm release is actually published.

Connect an AI client

Codex CLI

codex mcp add whatbox -- node /absolute/path/to/whatbox-mcp/dist/index.js
codex mcp get whatbox

Registration is a one-time setup. Codex launches the registered stdio server automatically; do not keep npm start running in another terminal. See the Startup Guide for the exact macOS reboot, SSH-agent, and daily launch sequence.

The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration on the same Codex host. See the official OpenAI MCP documentation.

Claude Code

claude mcp add --scope user whatbox -- node /absolute/path/to/whatbox-mcp/dist/index.js
claude mcp get whatbox

See the official Claude Code MCP documentation.

Generic stdio client

{
  "mcpServers": {
    "whatbox": {
      "command": "node",
      "args": ["/absolute/path/to/whatbox-mcp/dist/index.js"]
    }
  }
}

Do not put Whatbox credentials in the MCP client configuration. The server loads its private local file and checks its permissions.

Agent-first interface

The preferred workflow for an AI agent is:

1. read whatbox://guide/agent-operations;

2. call server_info and list_capabilities;

3. call whatbox_configuration_status;

4. use whatbox_operational_snapshot for the consolidated assessment;

5. call focused read-only tools only when additional detail is required.

The server also provides the whatbox_safe_audit prompt with full, storage, services, and website focus options.

All successful tool calls return both structuredContent and a serialized JSON text block for compatibility. Declared output schemas help compatible clients validate results before passing them to a model.

Read the Agent Usage Guide for operating rules and tool selection.

Tools

Mutation tools (require WHATBOX_MUTATIONS_ENABLED=true)

Read-only tools are annotated read-only; mutation tools are annotated non-read-only, and destructive tools carry the destructive hint. Annotations are hints, never authorization.

What agents can ask

Examples:

• “Perform a full safe audit of my Whatbox slot.”

• “Is storage pressure becoming a problem?”

• “Which supported services appear configured or running?”

• “Map the top two levels of allowed root 0.”

• “Assess whether the slot is ready for userland Nginx hosting.”

• “Test Nginx syntax and the configured loopback endpoint without returning logs or response content.”

• “Validate this allowlisted static-site source and show the deployment plan.”

The agent should always separate observed facts from recommendations and should never describe a running process as healthy without a health check.

Architecture

flowchart LR
  A[AI client] -->|MCP stdio| M[Whatbox MCP]
  M --> G[Agent guide resource and safe-audit prompt]
  M --> C[Local private configuration]
  M --> P[Local signed approval state]
  M -->|Pinned SSH and bounded SFTP| W[Owner-authorized Whatbox slot]
  M --> V[Local static-site validation]
  V --> Q[Signed deployment-plan preview]
  Q -. execution disabled .-> W

The MCP cannot access provider billing, another customer's files, root-only operations, Manage Apps, or managed links through SSH. DNS, domains, and provider-account actions remain explicit external steps unless a separate authorized integration is added.

Security model

• No generic remote shell tool.

• No caller-supplied command strings.

• No credentials in tool arguments or results.

• Private configuration must be mode 0600.

• SSH host identity is pinned by SHA-256 fingerprint.

• SSH-agent authentication is recommended.

• Remote paths are restricted to configured non-root allowlists.

• Canonical path checks deny traversal and symlink escapes.

• Fixed remote queries have bounded output.

• Sensitive directories and credential-like local source names are denied.

• Storage results omit configured remote root paths.

• Process state is collected from allowlisted command names without arguments.

• Website diagnostics use fixed /usr/sbin/nginx and /usr/bin/curl probes; configuration text, HTTP bodies, and log lines are never returned.

• Tool annotations are hints, never authorization.

See Security Policy and Architecture and Product Scope.

Mutation and approval model

Mutations are off by default. Set WHATBOX_MUTATIONS_ENABLED=true in the private local configuration to enable the mutation tools; without it every mutation tool returns a mutations_disabled denial.

Every mutation:

1. creates an immutable HMAC-signed plan before execution;

2. binds the exact slot, action, and canonical target digests;

3. expires within a short fixed window (5 minutes; 10-minute hard maximum);

4. is recorded in a redacted local audit log.

Reversible actions (upload, download, move, mkdir, backup, service start, website deploy, torrent add/control) run once the plan is created.

Destructive actions (quarantine, purge, service stop/restart, website rollback, torrent remove) additionally require negotiated MCP elicitation: round one returns input_required carrying the sealed plan as signed requestState; the retry must carry an accepted human elicitation response and the untampered plan, whose action, slot, and exact targets are revalidated before one-time consumption. A boolean or confirmation phrase supplied by a model is never sufficient — approval comes from the client's own confirmation UI.

Deletion has stronger rules: initial removal means quarantine (data is moved, not erased, so it is reversible and space-neutral), and permanent purge requires a separate second approval. Uploads, moves, and mkdir never overwrite; remote and local free space are checked before every transfer and deployment.

Local configuration

Private values live at:

~/.config/whatbox-mcp/local.env

The directory must be mode 0700 and the file mode 0600. Copy variable names from .env.example; never commit or share real values.

After local setup, use sanitized checks:

npm run check:config
npm run check:connection
npm run check:storage
npm run check:directory
npm run check:torrent-clients
npm run check:structure
npm run check:services
npm run check:review
npm run check:website
npm run check:website-diagnostics
npm run check:snapshot

Share only the emitted JSON, never private files or raw SSH debugging output.

Development

npm ci
npm run typecheck
npm test
npm run build
npm audit
npm pack --dry-run

Run the server from source:

npm run dev

Run the production build:

npm start

These manual commands are for development and protocol debugging. They wait silently for an MCP client over standard input/output and are not needed for normal Codex use. Diagnostics must use standard error so they do not corrupt the protocol stream.

Roadmap

Shipped in 0.10.0: SFTP release staging with remote checksum validation, the signed input_required approval handshake with denial-path coverage, atomic static-site activation with health check and rollback, redacted audit logging, approval-gated service lifecycle actions, and torrent management through a loopback RPC tunnel.

Next:

• service-specific health adapters beyond userland Nginx;

• multiple separately authorized Whatbox connection profiles;

• optional authorized provider integration for Manage Apps and managed links;

• a separately threat-modeled remote transport.

PHP application deployment is intentionally deferred until the static deployment and rollback path has been broadly live-validated.

Documentation

Contributing and reporting issues

Issues and pull requests are welcome after the initial public repository is established. Never include real credentials, hostnames, usernames, private paths, raw SSH output, cookies, tokens, or approval state in an issue.

Report suspected security vulnerabilities privately as described in SECURITY.md.

License

MIT