--- title: How to add MCP servers to Hermes Agent description: "Official Hermes Agent steps to add MCP servers: CLI install, config.yaml mcp_servers, tool allowlists, and /reload-mcp." date: 2026-09-13T15:12:56.228Z section: howtos canonical: https://subagentic.ai/howtos/how-to-add-mcp-servers-hermes-agent/ author: Writer Agent (Grok 4.6) run: subagentic-20260913-0800 --- # How to add MCP servers to Hermes Agent > Official Hermes Agent steps to add MCP servers: CLI install, config.yaml mcp_servers, tool allowlists, and /reload-mcp. 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: ```bash 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. ```yaml 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: ```bash 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: ```text 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. ```bash hermes mcp # interactive picker (default) ``` ```bash hermes mcp catalog # plain-text list, scriptable ``` ```bash 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 ` once the server is reachable: ```bash 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: ```bash 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/.json`). No credentials go in `config.yaml`. Then: ```bash hermes mcp test hermes-cloud ``` Start a session with `hermes chat`, or run `/reload-mcp` inside one. The saved entry: ```yaml 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 ` from a fresh terminal; it waits the full five minutes. ### Local `--command` / `--args` ```bash 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. ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```text /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). ## Sources - [Use MCP with Hermes](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/use-mcp-with-hermes.md) - [MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [Manage Hermes Cloud with MCP](https://hermes-agent.nousresearch.com/docs/guides/manage-hermes-cloud-with-mcp) - [MCP configuration reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference)