Experimental Cardano Pool MCP

Unmaintained — September 2026. BEACN's own pool retired at epoch 656, so this starter will not receive updates. It stays public as a reference; read the safety notes below before adapting any of it. BEACN archive

v0.1.0-experimental — reference implementation, not a turnkey mainnet product.

An MCP server for inspecting the design of guarded pool maintenance and adapting it to your own infrastructure. Built from work on a private BEACN deployment. This distribution contains no private deployment configuration or Git history.

The default is a local simulation in SAFE mode. It does not contact Cardano, read real signing keys, use SSH, or control system services. Every successful simulation response is labeled. Its health values are synthetic.

The included Linux/SSH adapters can affect a live block producer only after separate operator integration. Bugs, wrong configuration or failed recovery can interrupt block production. No independent security audit or production acceptance is claimed for this public version. Validate an isolated testnet deployment before considering mainnet.

Start here, SPOs

Download the experimental starter, unzip it, and open the extracted folder in a terminal. Follow the quickstart below to try the local simulation first. Fork the repository to adapt it. Do not point an AI at your production node and ask it to install this blindly.

For a deeper review: three-mode simulation, architecture and safeguards, production integration requirements, and what the tests establish.

Related MCP server: dsh-sim

Try it locally

Linux with Python 3.12 or newer. Use an ordinary user, not sudo.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps .
.venv/bin/python scripts/smoke_mcp.py

The smoke test uses the actual MCP SDK/stdio transport. It reads simulated health, creates an inert plan and verifies that SAFE mode refuses execution. It neither enables maintenance nor connects to a real node.

Register the following with an MCP client, replacing only the executable path:

{
  "mcpServers": {
    "experimental-cardano-pool": {
      "command": "/absolute/path/to/checkout/.venv/bin/cardano-pool-mcp",
      "args": []
    }
  }
}

No API token is required for this local MCP. The client may have its own model provider/account requirements. The default demo is temporary and resets when the server exits. Persistent simulation and mode exercises demonstrate assisted approval, experimental execution and failure recovery.

Three modes

Neither approvals nor mode changes are MCP tools. In production they must be controlled by an independent operator identity. The demo uses your local user for both sides to make experimentation convenient; it does not prove OS privilege isolation. An agent with that user's shell access can change demo policy. An administrator can also bypass a production MCP using separate access.

Six tools

No shell tool, arbitrary file reader, cold-key path, approval flag or mode setter is accepted in an MCP request. Strict schemas and runtime validation reject unexpected fields, invalid types, duplicate JSON keys and oversized frames.

Rotation and signing boundary

The engine records intent, stages a verified pair, rechecks authority, stops the services, atomically switches the credential generation, restarts, checks health and commits. Failure attempts a checked rollback. Unsafe recovery ends in RECOVERY_REQUIRED with startup inhibited. See architecture.

Fresh cold-key signing is not implemented. The signer interface returns SIGNER_REQUIRED; a finite pre-signed inventory is the only autonomous source. Do not copy someone else's KES ladder, counter, genesis anchors or acceptance record. This adapter supports a conservative same-counter ladder whose counter matches the observed chain state. Unknown counters and fresh issuance require a separate operator review. Integration limits.

What's included

• Runnable stdio MCP simulation, three modes and operator-only demo controls.

• Durable transaction engine, atomic generation logic, approval and audit code.

• Signature verification and a signer abstraction that refuses fresh signing.

• Linux/SSH/broker/launcher/monitor reference adapters and invalid-by-default example configuration; no production installer.

• Synthetic tests for input rejection, approval tampering, commit/rollback, process death, storage failure, startup guards and protocol boundaries.

• MIT license and security reporting guidance.

The private deployment's dashboard, personal host automation, VM power helpers, real certificates, logs, operational receipts and credentials are excluded. pool_status and pool_checks provide the monitoring interface for an optional dashboard. No public website, HTTP listener or automatic cron is installed.

.venv/bin/python -m pytest -q
.venv/bin/python scripts/release_check.py

See validation for what was actually tested. Passing tests does not establish safety for another operator's production setup.