MCP Servers

11.1. MCP Servers — The Open Tool-Connection Platform

MCP Servers — the open tool-connection platform. If you have to pick one integration to understand deeply first, pick this one. MCP (Model Context Protocol) is the open standard that lets Hermes connect to any tool server that implements the protocol — filesystem, databases, browser stacks, internal company APIs, or ready-made community services — without writing a single line of native tool code in the Hermes core.

Basic configuration

MCP servers are declared in ~/.hermes/config.yaml under the mcp_servers key:

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

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

After configuring, run /reload-mcp in a chat session to reload all servers without restarting Hermes.

Two transport types

• stdio — the server runs as a local subprocess and communicates over stdin/stdout (like the filesystem example above). Suitable for tools running on your machine.
• HTTP/StreamableHTTP — a remote server that Hermes connects to directly. This is the common type for hosted SaaS (Linear, Sentry, Atlassian, Asana, Figma, Stripe…).

For HTTP servers that require OAuth 2.1 (most hosted MCPs today), you only need to set auth: oauth — Hermes takes care of all the hard parts itself: discovery, PKCE, token exchange, refresh, and even step-up auth when the server asks for additional verification mid-session.

How the agent calls tools — clear namespaces

Every tool from an MCP server is named following the mcp__<server>__<tool> pattern to avoid collisions:

tool "read_file" from server "filesystem"  →  mcp__filesystem__read_file

You do not need to remember these internal names — the agent calls them transparently. But when you are reading logs/transcripts to debug, knowing this naming rule helps you trace which tool from which server is actually running.

The real-world problem: too many tools make the agent less accurate

This is the point most worth discussing in detail. When you attach several MCP servers at once, the agent has to “see” the full schema of every tool from the start — which burns context and reduces tool-selection accuracy, because too many options create noise.

The solution is Tool Search — a bridging mechanism (tool_search / tool_describe / tool_call) that defers loading detailed schemas until the model actually needs the tool:

• Anthropic’s evaluation showed accuracy improving from 49% to 74% on Claude Opus 4 when working with large tool catalogs.
• With small toolsets (few servers, every tool used every turn), Tool Search usually does not bring significant benefits — the bridge only adds unnecessary overhead.
• Hermes’s core tools (terminal, read_file, web_search, send_message…) are never deferred — because they are almost always needed.

Field-tested lessons

• Always filter with tools.include when connecting a new MCP server, especially one that touches sensitive data — do not open up the server’s entire toolset just because it is convenient. The example above enables only 4 of the GitHub server’s many tools, with no delete or merge rights.
• If you notice the agent picking the wrong tool, or responses getting noticeably slower after attaching a few MCP servers, that is a sign to check whether Tool Search is enabled at the right threshold (15+ tools attached at once is the point where this mechanism’s benefits start to show clearly).
• Start with a “safe” server first — e.g., a filesystem restricted to one project directory — before expanding to servers with write/delete rights on a real system.
• After changing mcp_servers in the config, remember to run /reload-mcp — skipping this step is the most common cause of “I already configured it but the agent still cannot see the new tools”.