Skip to main content

Connecting Hermes Agent to Atlas

Hermes Agent is a self-improving AI agent CLI/ gateway by Nous Research. Atlas doesn't bundle it — install it yourself following its own quick-install instructions. This page only covers pointing Hermes's MCP client at Atlas's MCP server (docs/API.md's "MCP" section) so it can use Atlas's inventory/advisor tools during an on-call or ops session.

1. Build the gateway with MCP support​

MCP support is a default-off Cargo feature:

cargo build --release -p atlas-gateway --features mcp
# or for local dev:
cargo run -p atlas-gateway --features mcp

2. Mint a scoped token for Hermes​

POST /auth/tokens requires an admin token. Mint an operator-role token for Hermes to use day to day — none of the exposed MCP tools need admin, and ops_advisor specifically requires operator or higher:

curl -sS -X POST http://127.0.0.1:5110/api/atlas/v1/auth/tokens \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H 'Content-Type: application/json' \
  -d '{"subject":"hermes-agent","role":"operator","ttl_secs":7776000}'
# 201 → { "token": "<jwt>", "jti": "jti_...", ... }

ttl_secs above is the 90-day maximum; pick something shorter if this token will live in a config file you don't want to worry about. Revoke it any time with POST /auth/tokens/{jti}/revoke (docs/API.md's "Token revocation & rate limiting" section) — this doesn't affect any other token.

3. Point Hermes at Atlas​

Add Atlas as a remote MCP server in Hermes's own config (~/.hermes/config.yaml):

mcp_servers:
  atlas:
    url: "http://127.0.0.1:5110/api/atlas/v1/mcp"
    headers:
      Authorization: "Bearer <the token from step 2>"

For an HTTPS deployment, use the gateway's ATLAS_HTTPS_ADDR host/port instead.

What Hermes can do through this​

The full tool catalogue (inventory, advisory, I/O risk, DR, jobs, plus the opt-in guarded create_snapshot) and the threat model are in MCP.md. A ready-made token script, client configs and an ops skill are under examples/agent/.

Everything is read-only/advisory by default. Nothing here can fail over, promote, delete, restore or wipe, and acting on an analysis (resizing a volume, cordoning a backend, running a failover) still means atlasctl or the REST API with a human in the loop. The only write paths are the opt-in, two-phase create_snapshot and ack_alert described in MCP.md.