---
name: hermes-mcp-server-ops
description: Add and troubleshoot MCP servers in Hermes gateway on the VPS — config.yaml mcp_servers block, hermes config set string-vs-list pitfall, stdio transport constraints, and the mcp==1.0.0 errlog incompatibility. Use when wiring any new MCP server into Hermes, debugging "failed to connect" errors, or when the gateway won't spawn an MCP process.
---

# Hermes MCP server operations

## Adding an MCP server to Hermes

Edit `~/.hermes/config.yaml` (agent-write-protected — use `hermes config set` or ask user to edit):

```yaml
mcp_servers:
  <name>:
    command: /path/to/command
    args: ["arg1", "arg2"]
```

**Critical pitfall:** `hermes config set mcp_servers.<name>.args '["serve"]'` writes the value as a **quoted YAML string**, not a list. The gateway fails to spawn the server. Fix by hand:

```bash
sed -i "s|args: '\\[\"serve\"\\]'|args: [\"serve\"]|" /root/.hermes/config.yaml
```

Or use `hermes mcp add <name> --command <cmd>` which may handle lists correctly (untested).

## stdio transport constraints

- The gateway spawns one process per MCP server, holding it for the gateway's lifetime.
- If the MCP server wraps a single-writer DB (PGLite, SQLite), the CLI is locked out while the gateway runs. Plan maintenance windows or use MCP-native tools if available.
- MCP tool lists are cached per session. A session started before the server was added won't see the tools — start a fresh session.

## mcp==1.0.0 errlog incompatibility

Hermes 0.19.0's `tools/mcp_tool.py` passes `errlog=` to `stdio_client()`, but the venv pins `mcp==1.0.0` which lacks that kwarg. Fix with the PGLITE-SHIM patch (inspect.signature check before passing errlog). **Wiped by `pip install --force-reinstall`** — reapply after any venv rebuild.

## Verification

After gateway restart, check:
1. `journalctl -u hermes-gateway | grep -i "mcp\|<server-name>"` — no "failed to connect" errors
2. `pgrep -af "<server-command>"` — process running as child of gateway
3. `hermes mcp` — server shows "custom — enabled"
4. Fresh session → ask a question that requires the server's tools → confirm tool call fires

## GBrain instance

See `gbrain-vault-mcp` skill for the concrete install. Key facts:
- 106 MCP tools, read-only surface (no import/embed via MCP)
- PGLite single-writer: CLI blocked while gateway runs
- Freshness cron `/root/.hermes/scripts/gbrain-refresh.sh` stops gateway, runs CLI, restarts