Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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

Capability Public beta
Durable run submit/status/wait/events Stable
Durable stop/steer/history Stable
Multi-profile routing Stable
Shared Desktop/TUI live attach Experimental / optional
Interactive approval/clarify requests Not implemented
Remote Streamable HTTP MCP Not implemented

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

Upgrading an installed copy

uv tool install is idempotent: if a requirement pin already exists for the tool, re-running it resolves and reports the same versions without upgrading. To move an installed copy to a newer release, force the reinstall:

uv tool install --force hermes-control-mcp

To move to a specific version, or to keep the pin and reinstall exactly it:

uv tool install --force "hermes-control-mcp==0.2.0b4"

If the pin must be replaced because a newer version was published, --upgrade (-U) relaxes the recorded pin:

uv tool install --upgrade hermes-control-mcp

After any upgrade, re-run the readiness check:

hermes-control-mcp doctor

The same pinning behaviour applies to pipx install and to pip install in an existing virtual environment, where an already-satisfied requirement is left alone unless you pass --upgrade.

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:

Bridge location What to configure Live owner attach
Same host as Hermes usually defaults + local Hermes .env are enough possible with compatible owner seam
Another VM/host --api-url + bridge-side key/env file; Hermes must be reachable over LAN/VPN/tunnel not through the owner lease
Launched on Hermes host through SSH remote MCP client uses SSH; bridge still uses local Hermes config/secrets recommended remote shape for experimental live attach

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):

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 owner seam is an out-of-tree patch, so a hermes update removes it. When a lease still exists but points at a dead PID, the bridge reports the owner process as not live. scripts/reapply-owner-adapter.sh --check reports both conditions without changing anything; running the script without --check re-applies the seam. Restarting the Hermes owner process afterwards is a separate, deliberate step - the script never restarts services itself.

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

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

Metadata

Release files for hermes-control-mcp 0.2.0b5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hermes-control-mcp 0.2.0b5
File Size Uploaded Provenance Actions
hermes_control_mcp-0.2.0b5.tar.gz 105.5 kB With provenance Details for hermes_control_mcp-0.2.0b5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hermes-control-mcp 0.2.0b5
File Interpreter ABI Platform Actions
hermes_control_mcp-0.2.0b5-py3-none-any.whl Python 3 none any Details for hermes_control_mcp-0.2.0b5-py3-none-any.whl

Total release size: 177.1 kB

Release files / hermes_control_mcp-0.2.0b5.tar.gz

Download URL hermes_control_mcp-0.2.0b5.tar.gz
Size 105.5 kB
Tags Source
SHA-256 checksum
How to use checksums
3776b7c16d67d7e24f2ff472fb74c70a9f6cee4ffe52ac5ba1df4a2dfc329a7f
BLAKE2b-256 checksum
How to use checksums
f65a31bf084f3230b53d3e5f4a80ccef04193c65dce8f04cdaae9c80d330fdd5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Release files / hermes_control_mcp-0.2.0b5-py3-none-any.whl

Download URL hermes_control_mcp-0.2.0b5-py3-none-any.whl
Size 71.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a2fbd9e931f950dada896f1f64d4ca4be2a7f94a462c84f7eca3f36bd9d8781a
BLAKE2b-256 checksum
How to use checksums
4ffbcb71590986af0d61fa219c21d6c3c2a2b06bcb3d83738b55a62af1254768
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

Security for hermes-control-mcp 0.2.0b5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hermes_control_mcp-0.2.0b5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page