Hermes

Why this agent

Hermes Agent is the self-improving AI agent built by Nous Research. It speaks MCP natively — per website/docs/user-guide/features/mcp.md — and reads MCP servers from ~/.hermes/config.yaml under the mcp_servers: (snake_case) top-level key. It supports both stdio and HTTP MCP transports, plus per-server tool filtering, sampling, and parallel-tool-call opt-in.

Prerequisites

• Hermes installed (one-line: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash).
• espctl installed at a stable path on disk.
• (Optional, for remote builds) the Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Edit ~/.hermes/config.yaml and merge this entry under mcp_servers: (create the file if it doesn’t exist — hermes setup will have populated other keys; just add mcp_servers alongside them):

mcp_servers:
  espctl:
    command: /path/to/espctl
    args:
      - mcp
      - serve
    env:
      CONTROL_BASE_URL: https://esphome.cloud
      MCP_AUTH_SECRET: your-access-key

Replace:

• /path/to/espctl — full path to your espctl executable.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — the access key your build server gave you.

Or grab the same snippet pre-filled:

Read the install://hermes resource.

Inside Hermes (after editing the config), pick up the new server with:

/reload-mcp

No restart needed.

First-run verification

hermes

Then in the Hermes TUI:

What espctl tools do you have?

Expected: Hermes lists ~40 espctl tools, all prefixed mcp_espctl_<tool_name> per Hermes’s namespacing convention.

Troubleshooting

• config.yaml parse error at startup — confirm 2-space indent, command: is a string (not array), args: is a list (one item per line, dash-prefixed), env: is a map (key-value pairs).
• Tools listed but every call returns “auth required” — the MCP_AUTH_SECRET is missing or has been revoked. Get a fresh access key from the control plane and paste it into the config.
• Want HTTP transport instead of stdio? Replace the command block with url: https://esphome.cloud/mcp/esp-idf and add headers: { Authorization: "Bearer your-access-key" }. Hermes handles both transports in the same mcp_servers: map.
• Want to filter exposed tools? Hermes supports tools.include: / tools.exclude: per server. For example, tools: { include: [build, flash, monitor] } exposes only those three.
• Parallel tool calls? espctl tools are mostly read-only enumerations and remote-build kickoffs. If you trust the concurrency, add supports_parallel_tool_calls: true to the server entry.

Tested as-of 2026-05-19

Hermes-specific notes

• The schema supports sampling: per server (Hermes can let the MCP server request LLM inference from Hermes itself); this MCP coverage doesn’t use sampling, so leave that block out.
• Hermes also publishes itself AS an MCP server via hermes mcp serve — so other agents (Claude Code, Cursor, …) can drive Hermes’s messaging surface. That’s the inverse direction; doesn’t affect the espctl-as-MCP-server configuration above.
• Tool names are auto-prefixed mcp_espctl_* to avoid colliding with Hermes’s built-in tools.