# Hermes Mcp Manager

> Manage MCP servers from chat for Hermes Agent: always-in-context server catalog + /mcp slash command to toggle a server's tools live, persisted, no restart

- **Type:** MCP server
- **Install:** `agentstack add mcp-pinkyhi-hermes-mcp-manager`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pinkyhi](https://agentstack.voostack.com/s/pinkyhi)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [pinkyhi](https://github.com/pinkyhi)
- **Source:** https://github.com/pinkyhi/hermes-mcp-manager

## Install

```sh
agentstack add mcp-pinkyhi-hermes-mcp-manager
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# hermes-mcp-manager

Manage MCP servers **from chat** for [Hermes Agent](https://github.com/NousResearch/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](https://github.com/NousResearch/hermes-agent/pull/2465)) covers discovery and per-tool selection *outside* sessions — [open question #5 of the original design issue](https://github.com/NousResearch/hermes-agent/issues/690) ("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](https://github.com/pinkyhi)
- **Source:** [pinkyhi/hermes-mcp-manager](https://github.com/pinkyhi/hermes-mcp-manager)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pinkyhi-hermes-mcp-manager
- Seller: https://agentstack.voostack.com/s/pinkyhi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.