gbrain/docs/mcp/HERMES.md

Connect GBrain to Hermes

This page is the MCP-registration reference for Hermes (the NousResearch hermes-agent). For the full brain install — CLI, engine, skills, dream cycle — follow INSTALL_FOR_AGENTS.md first; this page wires the finished brain into Hermes over stdio MCP.

Hermes spawns gbrain serve as a local stdio subprocess. No server, no tunnel, no token needed. Works with both PGLite and Supabase engines.

Register (recommended)

printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve

hermes mcp add performs a real MCP handshake and tool discovery at add time, then prompts Enable all N tools? [Y/n/select]:. Three gotchas, all observed:

• --args must be the LAST option. Everything after it — including a misplaced --env — is swallowed into the server argv. To pass several environment variables, list them all after ONE --env flag (--env A=1 B=2); repeating the flag replaces the earlier values and the server is saved disabled when its handshake then fails. Put --env and --connect-timeout before --command, exactly as above.
• Pipe the Y in non-interactive contexts. EOF on the enable-tools prompt prints Cancelled. and saves nothing. The piped Y saves the server with all tools enabled.
• The exit code is 0 even on connection failure or cancel. Never assert on mcp add's exit status — verify with hermes mcp list and hermes mcp test gbrain (below).

Direct config (equally supported)

The add command writes an mcp_servers block into $HERMES_HOME/config.yaml (default ~/.hermes/config.yaml). You can write it yourself instead:

mcp_servers:
  gbrain:
    command: gbrain
    args:
      - serve
    env:
      GBRAIN_HOME: /home/alice-example
    connect_timeout: 60.0
    enabled: true

To remove gbrain, delete this block (or set enabled: false to disable without losing the config).

Verify

hermes mcp list           # table row: gbrain ... ✓ enabled
hermes mcp test gbrain    # exits 0 and prints the discovered tool list

Then one real round-trip:

hermes -z "ask my gbrain brain: what did I import most recently?"

hermes -z prints the final answer on stdout (benign notices may appear on stderr). Inside Hermes, gbrain's tools appear namespaced as mcp_gbrain_<tool> (e.g. mcp_gbrain_search).

Headless auth + model pin

For cron jobs, CI, or any non-TTY run, Hermes needs a provider key and a default model configured without the interactive picker:

• Put the key in $HERMES_HOME/.env:

  ANTHROPIC_API_KEY=sk-ant-...
  # or OPENROUTER_API_KEY / OPENAI_API_KEY
  

• Pin the model non-interactively (hermes model is interactive-only — never use it in scripts or CI):

  hermes config set model.default anthropic/claude-haiku-4.5
  hermes config get model.default   # reads it back
  

Pair with cron

Hermes cron is fully non-interactive, which makes it a natural scheduler for brain maintenance:

hermes cron create --name gbrain-sync '0 */4 * * *' 'Run gbrain sync and report anything unusual'
hermes cron tick    # run due jobs once and exit — deterministic testing
hermes cron list

See docs/guides/cron-schedule.md for the full brain maintenance protocol (sync, embed, dream cycle).

Troubleshooting

• hermes doctor — global health check (installation, config, providers). It's not a per-server assertion; use hermes mcp test gbrain for that.
• agent failed: No inference provider configured (exit 1) — Hermes has no model key. Set one in $HERMES_HOME/.env and pin model.default as above.
• Relocating Hermes — both the installer and the runtime honor HERMES_HOME. All state (config.yaml, .env, SOUL.md, cron, logs) lives under it; the default is ~/.hermes. Export it consistently or the gbrain registration lands in a config file the runtime never reads.

---

Documented against Hermes Agent v0.20.0 (2026.8.3). Dev-facing observed-behavior notes (exact flag semantics, exit-code caveats, CI pin values) live in HERMES-CLI-PIN.md.