How to add MCP servers to Hermes Agent

Hermes Agent only sees MCP tools that are installed, connected, and allowed through. A wrong top-level YAML key, an enabled: false leftover, or an allowlist that drops every tool all look the same in chat: the server is in config, and the model never uses it.

Follow the official Nous path. Add one server under mcp_servers in ~/.hermes/config.yaml (or via the CLI), filter the surface, then run hermes chat and /reload-mcp.

Confirm MCP support is installed

If you used the standard install script, MCP support is already included — the installer runs uv pip install -e ".[all]". The feature page says the same: no extra step. If you installed without extras:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

For npm-based servers, make sure Node.js and npx are available. For many Python MCP servers, uvx is a nice default.

Add one server first

Start with a single, safe server. Official example: filesystem access to one project directory only.

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

That block is top-level mcp_servers in ~/.hermes/config.yaml. Coming from Claude Code, the mcpServers block in ~/.claude.json maps to this key — a silent miss if you paste the wrong name.

Stdio servers use command, args, and optional env. HTTP servers use url plus headers or auth: oauth. The config reference treats those as alternatives on each named entry.

Then start Hermes:

hermes chat

Ask something concrete — inspect the project and summarize the repo layout.

Verify the tools actually loaded

You can verify MCP in a few ways:

The Hermes banner/status should show MCP integration when configured
Ask Hermes what tools it has available
Use /reload-mcp after config changes
Check logs if the server failed to connect

A practical test prompt:

Tell me which MCP-backed tools are available right now.

Hermes prefixes MCP tools so they do not collide with built-in names. When you write include / exclude lists, use the original MCP tool name (hyphens and dots included), not the sanitized identifier Hermes registers for the model.

If the server is configured but nothing loads, check that enabled: false was not left in config, that the runtime exists (npx, uvx, and so on), that an HTTP endpoint is reachable, and that auth env or headers are correct.

CLI: catalog, URL + OAuth, or local command

Catalog (Nous-reviewed)

Hermes ships a curated catalog of MCP servers Nous staff has reviewed and merged. They are disabled by default — install only what you actually want.

hermes mcp                # interactive picker (default)

hermes mcp catalog        # plain-text list, scriptable

hermes mcp install n8n    # install a catalog entry by name

Hit Enter on a row to install (and walk through credentials), enable, disable, or uninstall. Catalog API keys are prompted at install time and written to ~/.hermes/.env. Remote OAuth entries are written as auth: oauth; the client opens a browser on first connection.

After credentials, Hermes probes the server and presents a tool checklist. Only checked tools end up in tools.include. If you select everything, no filter is written. If the probe fails, install still succeeds — re-run hermes mcp configure <name> once the server is reachable:

hermes mcp configure linear

That reopens the same checklist with your current selection pre-checked. GitHub is deliberately not in the catalog.

HTTP + OAuth

Example from the Hermes Cloud guide:

hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud

--auth oauth means an OAuth-protected HTTP server. On first connect Hermes discovers endpoints, registers as a client, opens your browser, and stores the token under ~/.hermes/mcp-tokens/ (per-server files such as ~/.hermes/mcp-tokens/<server>.json). No credentials go in config.yaml. Then:

hermes mcp test hermes-cloud

Start a session with hermes chat, or run /reload-mcp inside one. The saved entry:

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth

Pitfall: editing ~/.hermes/config.yaml from inside a running session auto-reloads MCP with a 30s timeout — not enough for interactive OAuth. Add the entry, then run hermes mcp login <server> from a fresh terminal; it waits the full five minutes.

Local `--command` / `--args`

hermes mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /absolute/path/to/repo
hermes mcp test open_scaffold

Always test the named server before you trust the session.

Whitelist tools before you expose a full surface

Do not wait if the server exposes a lot of tools. For financial, customer-facing, or destructive systems, use tools.include and start small.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

Read-only Hermes Cloud — list and inspect, never start/stop/create/destroy:

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth
    tools:
      include: [agents]

You can also blacklist with tools.exclude. If both include and exclude are set, include wins. Entries may be exact names or fnmatch-style globs.

Turn off Hermes-added resource/prompt wrappers when you do not want them:

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

tools.resources: false disables list_resources and read_resource. tools.prompts: false disables list_prompts and get_prompt. Those wrappers only appear if config allows them and the MCP session actually supports the capability.

If filtering removes all callable tools and no utilities remain, Hermes does not create an empty runtime toolset for that server. To keep config without connecting:

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Reload, then expand only when needed

After changing include/exclude lists, enabled flags, resources/prompts toggles, or auth headers / env:

/reload-mcp

Then grow the allowlist only when you need another tool. If expected tools are missing, the usual causes are tools.include, tools.exclude, resources: false / prompts: false, or a server that never supported those utilities. Seeing fewer tools than the MCP server advertises is expected — Hermes respects your per-server policy.

Next step: add one filesystem or catalog server, confirm the block sits under mcp_servers in ~/.hermes/config.yaml, then verify the connection the way the official guides do — hermes mcp test hermes-cloud after an OAuth add, or hermes mcp test open_scaffold after a local --command add. Start hermes chat, and ask which MCP-backed tools are live. If the list is empty, /reload-mcp and check logs before adding a second server. Keep the MCP config reference open for every field (timeout, connect_timeout, auth: oauth, globs).