Hermes MCP Control Plane

Hermes MCP Control Plane exposes Hermes Agent as a controllable MCP agent: durable runs, profile-aware routing, and optional shared live sessions with an existing Hermes Desktop/TUI runtime.

MCP host
   |
   v
hermes-control-mcp
   |-- durable --> Hermes API Server
   |
   '-- live ----> existing Hermes TUI gateway runtime
                  (optional / experimental)

The bridge is deliberately a control plane, not a second Hermes runtime. Hermes remains the authority for sessions, models, tools, approvals, profiles, and execution.

Status

The durable tier works against supported stock Hermes API Server deployments. Shared live attach currently requires a compatible owner/native attach seam and is intentionally not required for the public beta.

See Compatibility for the exact boundary.

Install

Python 3.11–3.14 is supported.

For a CLI application, an isolated tool environment is the recommended install:

uv tool install hermes-control-mcp

If you prefer plain pip, install inside a virtual environment:

python3 -m venv ~/.venvs/hermes-control-mcp
~/.venvs/hermes-control-mcp/bin/python -m pip install --upgrade pip
~/.venvs/hermes-control-mcp/bin/pip install hermes-control-mcp

On Debian/Ubuntu and other PEP 668 systems, running pip install directly against the system Python may fail with externally-managed-environment. That is an operating-system packaging guard, not a Hermes MCP compatibility error. Do not use sudo pip or --break-system-packages; use uv tool, pipx, or a virtual environment instead.

From source:

git clone https://github.com/upmeister/hermes-control-mcp.git
cd hermes-control-mcp
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Quick start

Hermes MCP Control Plane does not start or configure Hermes for you. Before the bridge can connect, Hermes must have its API Server enabled and the bridge must know both the API URL and the matching API_SERVER_KEY.

Choose your topology first:

Same-host happy path

If the MCP client and Hermes run on the same machine under the same user, this is the intended zero-friction path: after Hermes API Server is enabled, you normally need no --api-url, --env-file, or --profiles-root arguments. The bridge uses Hermes' local defaults and secret files.

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY '<strong-secret>'
hermes gateway restart

hermes-control-mcp doctor

A healthy durable-only deployment may report the live tier as unavailable and still return READY.

If Hermes is on another machine, do not expect the zero-argument doctor to discover it: the default API target is http://127.0.0.1:8642. Use --api-url and make the key available to the bridge, for example:

hermes-control-mcp doctor \
  --api-url http://192.168.1.50:8642 \
  --env-file ~/.config/hermes-control-mcp/hermes.env

For named profiles, SSH deployments, LAN exposure, state DB ownership, API_SERVER_KEY creation/resolution, platform limits, and doctor troubleshooting, read the Getting started and connection topologies guide.

MCP host configuration

MCP client configuration is not standardized by the MCP protocol. The familiar {"mcpServers": {...}} shape is common across several hosts and is accepted by ZCode's compatibility/full-config surfaces, but it is not universal: Codex uses TOML and VS Code uses a top-level servers object.

Instead of hand-writing these snippets, let the bridge generate the right shape:

hermes-control-mcp client-config zcode        # or: claude-code, cursor, codex, vscode

The command is non-mutating: stdout carries only the generated payload (guidance goes to stderr), no client, bridge, or Hermes configuration file is created or edited, and each config embeds an explicit absolute per-client state DB. For an MCP host on another machine, keep the bridge — and all Hermes secrets — on the Hermes host:

hermes-control-mcp client-config codex --ssh hermes-host

See the MCP client configuration matrix for exact same-host and SSH examples for ZCode, Claude Code, Cursor, Codex, and VS Code.

Repository examples (generated fixtures are byte-checked against the client-config renderers by tests):

• generated mcpServers fixture (Claude Code shape)
• ZCode → remote Hermes API — hand-written direct-API example, not generator output
• generated ZCode → SSH fixture
• ZCode → SSH + experimental live owner attach — hand-written example, not generator output
• generated per-client fixtures

MCP surface

Durable tools:

• run_start, run_status, run_wait, run_events
• run_stop, run_steer
• session_history
• bridge_health

Optional live tools:

• live_session_open
• live_prompt, live_wait, live_events
• live_status, live_history
• live_steer, live_interrupt
• live_reconcile, live_reconnect, live_health

The bridge does not expose arbitrary shell execution, raw gateway RPC, slash commands, Hermes config mutation, or credential mutation.

Multi-profile Hermes

Profiles are first-class routing boundaries:

(profile, lane) -> stored_session_id

For a named profile such as coder:

• durable API calls use Hermes /p/coder/... routes;
• the profile uses its own API_SERVER_KEY;
• live create/resume/control preserves the same profile;
• the default profile key is never borrowed for a named profile.

Probe profiles before connecting an MCP host:

hermes-control-mcp doctor --profile coder
hermes-control-mcp doctor --profile coder --profile research
hermes-control-mcp doctor --all-profiles

If an omitted profile can be inferred from exactly one existing local identity, the bridge reuses it. Ambiguous cross-profile routing fails closed instead of guessing.

Recovery and safety

• one logical durable request keeps one idempotency identity;
• uncertain mutations are reconciled rather than blindly resubmitted;
• stored session IDs and runtime session IDs remain distinct;
• reconnect/replay never proves ownership of a foreign completion by itself;
• failed/interrupted live turns return no answer payload;
• credentials and raw prompts are not persisted in the bridge registry;
• named-profile credentials never fall back to the default profile.

The public registry schema starts at version 1. Public-beta process ownership is one bridge process per state DB.

Live attach caveat

Shared live attach is currently experimental.

The deployed implementation joins the existing Hermes TUI gateway through a private local owner boundary. Stock Hermes v0.21.3 does not ship that project-specific owner seam.

Installing this package is therefore sufficient for the durable tier, but not by itself a promise that shared Desktop/TUI attach is available.

The project is tracking Hermes upstream native/session-authority work and intends to adapt the live transport when a supported upstream seam lands rather than maintain a permanent competing runtime.

See upstream research.

Hermes multiplexing note

Explicit Hermes multiplexing can activate configured platform adapters across multiple live profiles. Older installations with copied Telegram/Discord/etc. credentials may surface duplicate-credential conflicts during gateway startup.

The bridge detects profile/API readiness but deliberately does not rewrite Hermes profile topology or adapter configuration.

See Compatibility.

Development

pip install -e .
./scripts/test.sh
python -m unittest discover -s tests -v
python -m compileall -q src
python -m py_compile src/hermes_control_mcp/*.py
git diff --check

CI tests Python 3.11, 3.12, 3.13, and 3.14. It also builds wheel + sdist and performs clean installed-wheel MCP smokes on the lowest and highest supported interpreters (3.11 and 3.14).

Documentation

• Getting started and connection topologies
• MCP client configuration matrix
• Compatibility and support tiers
• Roadmap
• Hermes upstream research
• API Server / Agent Sessions research plan
• Distribution and upstreaming strategy
• Release process
• Security policy

Security

Please do not report credential leaks, auth-boundary bypasses, or cross-profile isolation bugs in a public issue. Use GitHub's Private vulnerability reporting for this repository.

See SECURITY.md.

License

MIT