hermes-fleet-mcp

An MCP server that exposes a Hermes deployment's state and a chat surface, so a control plane (or any MCP client) can observe and drive a remote Hermes box. This is the Node Bridge — one install per box, one bearer token per box.

Read-only observability (agents, sessions, crons, skills, tools) + a chat tool that runs a remote agent and returns a session handle to poll. No admin mutations.

License & Disclaimer

MIT licensed — free to use, modify, and redistribute, including for commercial use. See LICENSE.

Developed by Dynamics Mobile OOD (dynamicsmobile.com). The software is provided "AS IS" for use at your own risk: Dynamics Mobile OOD makes no warranties and accepts no responsibility or liability for any consequences, damage, or loss arising from its installation or use — including anything an agent does while driven through this bridge.

Related MCP server: hermes-gpt

Install (on the box)

Requires Python 3.10+ and a working hermes CLI on PATH.

pip install .            # or: uv tool install .

Run

# 1. generate a per-box token
hermes-fleet-mcp gen-key

# 2. serve the MCP endpoint (streamable HTTP) — bind only where you trust it
hermes-fleet-mcp serve --host 0.0.0.0 --port 8000 --token '<the key>'
#    (or --token-file key.txt, or env HERMES_FLEET_MCP_TOKEN)

The MCP endpoint is http://<host>:<port>/mcp. Every request must carry Authorization: Bearer <token>.

Serve over TLS in production — put it behind a reverse proxy (Caddy/nginx) or use an MCP-over-TLS transport. The token is a shared secret; plain HTTP leaks it.

By default the bridge accepts any Host header (it's a server-to-server endpoint, so the bearer token is the real gate). To keep DNS-rebinding protection on and whitelist your public domain instead, add --allowed-host yourdomain.com (repeatable; localhost is always allowed).

HERMES_HOME is honoured (default ~/.hermes); override with --hermes-home.

Docker

Run as a container — read-only observability works out of the box with HERMES_HOME mounted:

export HERMES_HOME=/home/hermes/.hermes
export HERMES_FLEET_MCP_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose up -d --build

The chat tool and the version field need the hermes CLI — see docker-compose.yml for how to make it reachable (build FROM a Hermes image, or mount the host install).

Tool surface

agent maps to a Hermes profile name (default is the root profile). The caller claim on chat is recorded for per-human attribution.

How agents map to Hermes

• Agent = Hermes profile. default = <HERMES_HOME>/config.yaml; named agents = <HERMES_HOME>/profiles/<name>/config.yaml.

• --profile <name> sets an isolated HERMES_HOME, so sessions/crons/skills are read per-profile.

• Chat runs hermes --profile <agent> -z "<message>" (one-shot: prints only the final reply, approvals auto-bypassed).

Connect from an MCP client

Point any MCP client at http://<host>:<port>/mcp with the bearer header. Example client config (DMOps or another MCP host):

{
  "mcpServers": {
    "hermes-fleet": {
      "url": "https://box.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Security

• Bearer token per box — generated by gen-key, validated (constant-time) on every request.

• Read + chat only — no admin mutation tools in this version.

• TLS required in production; never expose the endpoint anonymously.

• DNS-rebinding protection — off by default (server-to-server); opt in with --allowed-host <domain> to whitelist your public host while keeping it enabled.

Development

pip install -e ".[dev]"
pytest