Hermes Agent

The Hermes agent (Nous Research's open-source agent CLI) reads its configuration from ~/.hermes/config.yaml under your home directory. There is no project-scoped config file: unlike Claude Code's .mcp.json or Cursor's .cursor/mcp.json, everything merges into the one user-level file. The same streamable HTTP transport, Bearer key, and workspace-pin header used by every other MCP client applies.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, and the security gates that apply to every MCP request.

Quick Start

Download the Hermes Agent bundle from the Chat page's Client tab (visible once a specific workspace is selected). The zip contains hermes-config.yaml, a README, and HERMES.md. Merge the sections of hermes-config.yaml into ~/.hermes/config.yaml (create the file if it does not exist yet), then restart Hermes; the Erebine tools are discovered on the next launch.

To hand-author just the MCP connection, merge this block instead:

Replace the two placeholders. The path segment proj_ABC123 is your project's external id, already substituted into the URL above for the project you are signed into.

• <api_key>, a key with the inference scope. Mint one with erectl keys --create --name "Hermes Agent" --scopes inference.
• <workspace_id>, the ws_xxx identifier of the workspace this server entry pins to. List options with erectl workspaces list.

Generate the snippet from the CLI. erectl mcp setup --client hermes emits the ready-to-merge mcp_servers section with your project id substituted in. The CLI path is MCP-only; the inference model section below comes with the dashboard bundle.

Keep the key out of the repo. ~/.hermes/config.yaml lives outside your project tree, but the extracted hermes-config.yaml contains your workspace API key; merge it, then delete the extracted copy rather than leaving it in a tracked directory. Re-downloading rotates the key.

Inference Endpoint

The dashboard bundle's model section makes your workspace's endpoint Hermes' default model. Hermes treats any OpenAI-compatible server as provider: custom:

• context_length and max_tokens pin the advertised context window and output cap; Hermes cannot auto-detect them from a custom endpoint.
• default_headers opts every inference request into the router's corrective-retry augmentation, the same posture the other downloaded clients use.
• agent.reasoning_effort is emitted only for reasoning-capable models, seeded from the model family's default.

Project Rules

The bundle ships HERMES.md, the shared Erebine tool-use guidance every other client receives through its own rules surface. Save it at your project root; Hermes loads it automatically as project context at session start. Without it, the agent will sometimes ask you about workspace state instead of calling the Erebine tools to retrieve it.

Prompts and Resources

The Erebine MCP server exposes more than tools: each workspace also advertises 6 prompts and 4 resources alongside the tool catalog. Hermes does not render prompts as slash commands or resources as @-mentions; instead it registers per-server wrapper tools when the server advertises those surfaces:

• list_prompts / get_prompt, enumerate and expand the six server-authored prompts (e.g. brief, onboard).
• list_resources / read_resource, enumerate and read the four resource URIs (e.g. erebine://workspace/current/brief).

The model calls these like any other tool, so asking Hermes to "read the workspace brief resource" works without client UI support. The prompts and resources themselves are documented on the general MCP integration page.

Capability Matrix

The Hermes agent's MCP capability set, as surfaced to the Erebine router during the MCP initialize handshake, is:

• transport: streamable HTTP.
• authorization: Bearer header.
• custom headers: yes, used for the X-Erebine-Workspace pin.
• resources: via wrapper tools (list_resources / read_resource).
• prompts: via wrapper tools (list_prompts / get_prompt).
• sampling: yes, server-initiated LLM requests are supported and configurable per server.
• elicitation: no, the client does not expose a structured-input prompt to the server.
• roots: no, no workspace root is advertised to the server.

See the full per-client comparison in docs/mcp, Security.

Troubleshooting

Tools do not appear after editing the config

Hermes discovers MCP servers at session start. Restart the agent (or start a new session) after editing ~/.hermes/config.yaml; the next launch should list the Erebine tools in the startup banner.

The agent switched to an unexpected model

Merging the bundle's model section replaces Hermes' single global model selection. Restore your previous provider with hermes model, and keep only the mcp_servers section if you want Erebine tools without Erebine inference.

Project instructions stopped applying

A HERMES.md at the project root shadows AGENTS.md, CLAUDE.md, and .cursorrules, because Hermes loads only the first project context file it finds. Merge the contents into a single file if you need both sets of guidance.

401 Unauthorized on every tool call

The API key is missing, malformed, or has been revoked. Note that each Client-tab download rotates your personal key for the workspace, revoking the one in any earlier bundle. Re-merge the newest bundle, or mint a standalone key with erectl keys --create --name "Hermes Agent" --scopes inference.

403 Forbidden with code scope_insufficient

The API key authenticated but does not carry the inference scope required by the MCP surface. Mint a replacement key with the inference scope using the command above.

Requests overflow or truncate unexpectedly

Hermes sizes its context compression from model.context_length. If you changed the workspace's resolved endpoint after downloading, re-download the bundle so the pinned window matches the model actually serving the endpoint.