Hermes Mcp Manager

hermes-mcp-manager

Manage MCP servers from chat for Hermes Agent: a cheap always-in-context catalog so the agent knows what tool servers exist, and an /mcp slash command so the owner can toggle a server's tools on and off — live, persistent, no restart.

The problem

An agent with a dozen configured MCP servers faces a bad trade-off: load every server's full tool schemas (~45k tokens of context, every turn) or defer tool loading and have the agent not know what exists at all — it can't propose using a server it can't see. And once a session is running, the only lever is /reload-mcp (full reconnect of everything) or hand-editing config.yaml and restarting.

Upstream's hermes mcp CLI (#2465) covers discovery and per-tool selection outside sessions — open question #5 of the original design issue ("for gateway-only users, should there be a /mcp slash command?") is exactly the gap this plugin fills.

What it does

1. Catalog injection (~0.5k tokens, every top-level turn). The agent always sees a compact map:

[mcp-catalog] MCP servers configured for you — this is a MAP of what EXISTS, not your live tool list:
  chrome-devtools [active] (26 tools)
  playwright [active] (24 tools)
  spartan [off] (18 tools)  ← tools NOT loaded (cannot call)
  cloudflare-bindings [disabled] (0 tools)  ← tools NOT loaded (cannot call)
Only `active` servers' tools are loaded and callable. ... If a task needs an off/disabled
server, PROPOSE it and ask the owner to run `/mcp on `.

The agent proposes; only the owner enables. Deliberately no tool names for off servers — listing them makes models hunt for tools they can't call.

2. mcp_catalog tool (read-only). The same view on demand, with per-server descriptions.

3. /mcp slash command (owner-invoked, deterministic, no LLM). Works in Discord/Telegram/CLI — anywhere Hermes slash commands work, including the native Discord picker:

/mcp                     → list servers with state + tool counts
/mcp off playwright      → hide playwright's tools from the model
/mcp on playwright       → surface them again
/mcp playwright          → one-shot flip

How the toggle works

The server stays connected — the switch gates its mcp- toolset via agent.disabled_toolsets:

• Applied live to every reachable session through the core's refresh_agent_mcp_tools(agent, disabled_override=…) (the same machinery /reload-mcp uses) — no reconnect, no restart.
• Persisted to the profile config.yaml with an atomic fresh-read + temp-and-rename write, so it survives restarts and preserves concurrent edits. agent.disabled_toolsets is a cache-busting config key upstream, so the change takes effect from the owner's next message.
• Control-plane only. The plugin never touches MCP transport, never connects or disconnects anything, and keeps no second list — the catalog is always derived from the live registry + config.

Server states:

| State | Meaning | |---|---| | active | connected, tools surfaced to the model | | off | connected, tools hidden (/mcp off) | | disabled | enabled: false in mcp_servers config — not connected (reconnecting needs a restart; /mcp on can't do it, by design) | | unreachable | enabled in config but failed to connect |

Install

hermes plugins install pinkyhi/hermes-mcp-manager --enable

No required configuration. Optional:

| Variable / config | Default | Meaning | |---|---|---| | MCP_MANAGER_INJECT | 1 | Set 0 to disable the per-turn catalog injection | | MCP_MANAGER_MAX | 30 | Max servers shown in the injected catalog | | mcp_servers..description in config.yaml | — | Overrides the derived one-line description |

Requires a Hermes version with ctx.register_command (plugin slash commands) and refresh_agent_mcp_tools (both present in current releases).

Design notes

• Fail-open everywhere. A broken catalog returns nothing rather than breaking the agent's turn; a failed config write still applies the live toggle and says so.
• Subagents skip the injection — they don't manage MCP, keep their context lean.
• The owner typing /mcp is the authorization — the command is deterministic and never goes through the model, so there's nothing for a prompt injection to steer.

Tests

python test_offline.py

Offline suite with faked registry/config/agent — catalog merging, state derivation, toggle persistence, injection formatting, command parsing.

Roadmap

• Aux-LLM one-line server descriptions (derived from serverInfo + tool descriptions, cached per server) — current fallback is tool-name based.
• /mcp on flipping mcp_servers..enabled + reconnect.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pinkyhi
• Source: pinkyhi/hermes-mcp-manager
• License: MIT

Install and usage instructions live in the source repository linked above.