Hermes Agent MCP Tools Not Loading? Fix It Fast

You added an MCP server to ~/.hermes/config.yaml, restarted the gateway, and asked Hermes to list its tools. Nothing new is there. No error, no warning, gateway.log is quiet. This post is the shortest path from that silence to a working mcp_<server>_<tool> in your session.

Five failure modes cause almost every reported case, and each one hides in a different place. The good news: hermes mcp list, hermes mcp test, and one log-level flag will tell you which of the five you are looking at inside two minutes.

Why silent failures happen in the first place

MCP misconfiguration is the single most-underlogged surface in Hermes. When the loader cannot start a server, cannot import the Python mcp extra, or cannot parse the mcp_servers block, the failure is logged at DEBUG and never rises to gateway.log in the default install. From your side it looks like the config was accepted and the tools simply do not exist.

The fix is to escalate visibility before you touch anything else. Restart Hermes with verbose logging so the loader tells you why it gave up:

hermes serve --verbose
# or, if you launch through docker compose:
HERMES_LOG_LEVEL=DEBUG docker compose up

Now re-run hermes mcp list. If your server appears in the list but no tools are attached, the connection is up but tool discovery failed. If the server is missing entirely, the loader never registered it. That branch tells you which of the fixes below applies.

Cause 1: the mcp Python extra is not installed

If you built Hermes from source or pinned a specific tag, the mcp package is an optional extra and it is not pulled in by the default install. Without it, every entry under mcp_servers is silently ignored. This is the single most common cause on custom setups.

Reinstall with the extra enabled:

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

If your gateway now boots and starts trying to reach the server, you were missing the SDK. If the log still says mcp module not available, the extra did not install into the interpreter Hermes is actually running - check hermes --version for the venv path and re-run the install inside it.

Cause 2: your YAML indentation is off by one space

YAML silently drops any block whose indentation does not match its parent. A stray tab, a - at the wrong depth, or an unquoted colon inside a command string will disappear the entire mcp_servers map without a single warning line.

The safe shape is two-space indentation, quoted strings for anything with a colon, and lists rendered with -:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
  stripe:
    url: "https://mcp.stripe.com/v1/sse"
    enabled: true

Two quick sanity checks: run python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" to confirm the file parses at all, then run hermes mcp list to confirm the server names appear. If the file parses but the block is empty from Hermes' point of view, the indentation is wrong even though the syntax is legal.

Cause 3: node or npx is missing on the host

Most community MCP servers ship as npm packages and are launched with npx -y @modelcontextprotocol/server-<name>. If the host does not have Node.js on PATH, the subprocess exits before it prints anything and Hermes records the failure at DEBUG only. This is the most common cause inside minimal Docker containers.

Test the launch outside Hermes first:

node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp

If any of the three fails, install Node.js in the same environment Hermes runs in. In Docker, that means adding nodejs and npm to your image or picking a base image that already has them. There is no way for Hermes to launch a Node binary that is not there.

Cause 4: the server connects but its tools never surface

You see the server in hermes mcp list, hermes mcp test <server> discovers its tools, and yet nothing new is callable inside the session. This is the failure documented in issue #51587 and issue #71736: discovery succeeded, but the tools were never injected into the session toolset.

The reliable workarounds are:

• Run /reload-mcp inside your Hermes session, or restart the gateway entirely. Some builds populate the session toolset once at boot and miss servers that come up late.
• Check the enabled_toolsets field on the session. If it is scoped tightly (for example the ACP session hardcodes ["hermes-acp"]), MCP tools are excluded by design and need the toolset widened.
• Confirm your provider actually supports tool use. Ollama models must be launched with a Hermes-compatible tool template, and older local models will report tools discovered but never call them.

Cause 5: your provider silently drops tool calls

Even when the server is up and the tools are registered, some providers strip the tool payload before the model sees it. This produces the exact same symptom as a broken MCP server - the tool exists but nothing happens when you ask for it.

Two-minute check: switch the session to a known-good tool-calling provider (any recent Anthropic, OpenAI, or Groq model) and ask the same question. If the tool fires there, the problem is your provider or your model choice, not MCP. If it still does not fire, go back to Cause 4.

The diagnostic path, in order

Run these in this order and stop as soon as one changes what you see:

1. hermes serve --verbose - now failures print to stdout.
2. python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" - confirms the file even parses.
3. hermes mcp list - shows what the loader accepted.
4. hermes mcp test <server> - shows whether the connection and discovery work.
5. hermes mcp health - a per-server status snapshot when you need to hand something to a teammate.
6. /reload-mcp inside your session, or a full gateway restart.
7. Swap providers for a two-minute A/B.

For a full tour of the diagnostic surface, the Hermes debugging and observability guide covers gateway.log, per-tool call tracing, and how to tail everything cleanly. If you are still setting your first MCP server up, the MCP setup guide walks you through the config-file shape before any of the failures above become possible.

Skip the surface entirely

Every failure in this post is caused by an environment mismatch between Hermes and its host: a missing Python extra, a missing Node binary, a permission on a config file, a session boot ordering bug. Hermify runs the entire surface for you.

Get started with Hermify to run a managed Hermes Agent on Telegram with MCP already wired, the mcp extra installed, npx on the host, and reload-on-config-change working out of the box. You keep your MCP config, you keep your memory, and you stop diagnosing YAML indentation on a Tuesday night.

Sources

• MCP server misconfiguration is invisible - issue #31246
• MCP tools connect but never surface into session - issue #51587
• Inconsistent MCP tool availability with Ollama - issue #71736
• Hermes Agent MCP documentation
• Model Context Protocol debugging guide