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.

Leave the timeouts unset. Hermes defaults to a 300-second timeout for a tool call and a 60-second connect_timeout, both of which cover the Erebine server.

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, together with the inference providers and model sections below, built from the workspace's _direct models over the management API. Pass --mcp-only for the server entry alone.

The CLI's key placeholder needs one edit. By default erectl mcp setup writes Bearer {env:EREBINE_API_KEY}. Hermes does not expand that form and will send it literally. Either pass --inline-api-key <api_key> to write the secret directly, or rewrite the placeholder as ${EREBINE_API_KEY}, which Hermes does substitute from the environment (${env:EREBINE_API_KEY} works too).

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 registers your workspace as a named custom provider under Hermes' providers dict, selects it in the model block, and adds the MCP server alongside. That is the whole merged shape:

• providers.erebine is a named custom provider, one entry in Hermes' providers dict keyed by provider name. Adding it leaves every other provider you already configured in place.
• api is the endpoint base URL, api_key the workspace key, and transport: "chat_completions" the OpenAI-compatible wire format the Erebine endpoint speaks.
• The models mapping carries one entry per advertised model, each with its own context_length. A Direct routing-mode bundle lists the whole fleet here; the pinned and semantic modes list the single model that endpoint serves. Hermes still probes the endpoint's /models listing on top of this unless you set discover_models: false.
• supports_vision: true rides the entry of every model whose catalog row declares image input. It is the switch that makes Hermes send an attached image natively, as an image_url part; without it Hermes pre-describes the image through its vision_analyze tool and the model never sees the pixels. Text-only and audio-only entries omit the key.
• extra_headers opts every inference request into the router's corrective-retry augmentation, the same posture the other downloaded clients use.
• model.provider: "custom:erebine" selects that provider and model.default boots the session on the workspace default model. model.max_tokens is the output cap, the most tokens one response may generate; it is unrelated to the context window.
• agent.reasoning_effort is emitted only for reasoning-capable models, seeded from the model family's default.

Switch between the workspace's models mid-session with /model custom:erebine:<model_id>, or run the hermes model wizard to pick from the list.

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

Hermes registers every MCP tool as mcp__<server>__<tool>, with any character outside [A-Za-z0-9_] in either half replaced by an underscore. The Erebine tool erebine.intelligence.brief therefore appears as mcp__erebine__erebine_intelligence_brief, and every other tool follows the same mcp__erebine__erebine_<group>_<verb> pattern.

The 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, under the same prefix:

• mcp__erebine__list_prompts / mcp__erebine__get_prompt, enumerate and expand the six server-authored prompts (e.g. brief, onboard).
• mcp__erebine__list_resources / mcp__erebine__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 (mcp__erebine__list_resources / mcp__erebine__read_resource).
• prompts: via wrapper tools (mcp__erebine__list_prompts / mcp__erebine__get_prompt).
• sampling: yes, server-initiated LLM requests are supported and configurable per server.
• elicitation: form-mode, answered through Hermes' approval surface (an interactive prompt in the CLI or TUI, approval buttons on gateway platforms), enabled by default; URL-mode requests are declined.
• 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 block replaces Hermes' global provider and default-model selection. Restore your previous provider with hermes model, or point model.provider back at it by hand. The providers.erebine entry can stay: keeping it without the model block leaves Erebine reachable through /model custom:erebine:<model_id> while your old default keeps booting sessions. Keep only mcp_servers if you want Erebine tools without Erebine inference at all.

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 the window it resolves for the active model: model.context_length first, then providers.erebine.models.<model_id>.context_length, then auto-detection. The bundle writes the per-model form, because a top-level model.context_length outranks it and would apply the same window to every model you switch to. If you changed the workspace's resolved endpoint after downloading, re-download the bundle so the pinned windows match the models actually serving it.