Hermes Agent + MCP Servers: The Complete Setup Guide (2026)

What MCP Actually Gives a Hermes Agent

The Model Context Protocol is a standard interface between agents and external tools. Instead of writing a custom integration for every service, you point Hermes at an MCP server and the server tells Hermes what tools it offers. Hermes discovers configured servers at startup and registers their tools into the same registry its built-in tools live in — from the model's point of view, an MCP-backed tool is just another tool it can call.

Each registered tool gets a prefixed name: mcp_<server_name>_<tool_name>. So read_file from a server you named filesystem shows up as mcp_filesystem_read_file. That naming matters when you are debugging tool calls in the transcript or writing skill instructions that reference specific tools.

What this unlocks in practice: a GitHub server gives the agent issues and code search, a filesystem server scopes it to a project directory, a browser server (Playwright or Chrome DevTools) lets it drive a real browser, and a database server lets it answer questions from production data. The whole MCP ecosystem — hundreds of servers at this point — becomes available without Hermes-specific glue code.

One setup note before anything else: MCP support is installed as an extra. If your install was minimal, run this inside your Hermes directory first:

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

If you have not set up Hermes itself yet, start with our Hermes Agent setup guide and come back here once the agent is running.

Quickstart: Your First MCP Server in config.yaml

MCP servers live in the mcp_servers section of your Hermes config.yaml. The simplest case is a local stdio server: Hermes launches it as a subprocess using command and args, and talks to it over stdin/stdout. Here is the official filesystem server, scoped to one project directory:

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

Servers that need secrets take an env block. The GitHub server is the canonical example — and it also previews tool filtering, which we will get to properly in a moment:

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

You can stack multiple servers under one mcp_servers key. A typical local-project setup pairs filesystem access with git:

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

Restart Hermes (or run /reload-mcp) after editing the config, then verify with a direct question: "Tell me which MCP-backed tools are available right now." If the server loaded, the agent will list the prefixed tool names. That one-line sanity check catches most config typos before they cost you a confusing session.

Remote Servers: url Instead of command

Not every server should run as a local subprocess. Hosted services, internal company APIs, and anything shared across a team are reached as remote servers: you give Hermes a url instead of a command, and it connects over HTTP with SSE handling the streamed side of the protocol. Authentication is usually a bearer token in headers:

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer your-token-here"

Providers that support OAuth can skip static tokens entirely — set auth: oauth and Hermes walks the authorization flow for you:

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

The decision between stdio and remote is mostly about where the capability lives. Filesystem and git access are local by nature — keep them stdio, no network surface, secrets stay in local env vars. A hosted SaaS tool or a database gateway is remote by nature — use url and let the provider handle uptime. There is no performance reason to prefer one over the other for typical agent workloads.

Tool Filtering: The Smallest Useful Surface

This is the part most setup guides skip, and it is the part that separates a usable agent from a confused one. Every tool you register costs you twice. First in tokens: each tool definition rides along in the context on every single model call, so a GitHub server exposing 30 tools you never use is a permanent tax on every request. Second in decision quality: models pick wrong tools more often when the menu is long, and a wrong pick on a destructive tool is not a token problem, it is an incident.

Hermes gives you a tools block per server with two modes. include is an allowlist — only the named tools get registered:

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

exclude is a blocklist — everything registers except what you name. This is the right shape when a server is mostly safe but has a few tools you never want an agent touching autonomously:

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer your-token-here"
    tools:
      exclude: [delete_customer, refund_payment]
      resources: false

The prompts: false and resources: false flags drop the MCP utility wrappers (list_prompts/get_prompt and list_resources/read_resource) for servers where you do not need them — a few more tokens saved per call, and a shorter menu.

The principle: connect the right thing, with the smallest useful surface. Start from include with the two or three tools your agent actually needs, and widen only when a real task hits a wall. An allowlist that grows on demand beats a blocklist you discover was incomplete.

Worked Example: Governed Database Access

Databases are the highest-value, highest-risk MCP connection. The value is obvious — "how many signups did we get last week?" answered from real data instead of a guess. The risk is equally obvious: the naive setup puts raw Postgres credentials in your agent config and hands the model a connection that can DROP TABLE just as easily as it can SELECT.

The pattern we recommend instead is a governed gateway: a remote MCP server that holds the database credentials server-side and exposes only a read-only query surface to the agent. We will use AI2SQL's MCP endpoint as the example — full disclosure, it is our sister product, but it is also the setup we run ourselves, and the pattern applies to any governed SQL gateway. It exposes exactly three tools: run_query (read-only, writes blocked at the gateway), describe_schema, and list_connections. It requires an API key from an AI2SQL paid plan.

mcp_servers:
  ai2sql:
    url: "https://builder.ai2sql.io/api/mcp"
    headers:
      Authorization: "Bearer YOUR_AI2SQL_API_KEY"
    tools:
      include: [run_query, describe_schema]
      prompts: false
      resources: false

Walk through what this buys you compared to a raw database server:

• No database credentials in agent config. The Postgres or MySQL connection string lives on the gateway. The agent config holds an API key that can be rotated or revoked without touching the database.
• Read-only enforced server-side. Writes are rejected by the gateway's SQL guard, not by a prompt instruction the model might ignore. Prompt-level "please don't write" is a suggestion; a gateway rejection is a wall.
• Three tools, not thirty. The whole surface fits in a sentence, which keeps tool-choice accuracy high and token cost low. We dropped list_connections from the include list above because a single-database setup never needs it.
• Audit trail. Every query the agent runs is logged at the gateway, so when the agent produces a surprising number you can see exactly what SQL produced it.

After a restart or /reload-mcp, the agent sees mcp_ai2sql_run_query and mcp_ai2sql_describe_schema. A natural flow looks like: the agent calls describe_schema once to learn your tables, then answers questions with targeted run_query calls. Pair it with a small skill file that documents your schema's quirks (naming conventions, which table is the source of truth for what) and the answer quality jumps noticeably — see our Hermes skills guide for how to write that file.

If you would rather self-host the gateway layer, the same config shape works with any MCP server that enforces read-only SQL — the important part is the pattern (credentials server-side, minimal tool surface, writes blocked below the model), not the specific vendor.

Troubleshooting: The Three Failure Modes

1. Tools not appearing

Remember that discovery happens at startup: Hermes reads mcp_servers, launches or connects to each server, and registers tools then. If you edited config mid-session, the running agent has not seen it — restart, or run /reload-mcp. If tools still do not show up, work down this list: the MCP extras are installed (uv pip install -e ".[mcp]"); the server is not accidentally set enabled: false; the runtime in command actually exists on your PATH (npx and uvx are the usual suspects on fresh machines); and your tools.include list is not silently filtering out the tool you are looking for — an allowlist with a typo'd tool name fails quietly.

One nice property of the protocol: well-behaved servers can push a notifications/tools/list_changed notification when their tool list changes, and Hermes refreshes automatically — no /reload-mcp needed. That covers server-side changes; config-file changes on your side still need the reload.

2. Too many tools bloating context

Symptoms: responses get slower and more expensive, the agent starts picking odd tools for simple tasks, or small local models start failing tool calls outright. The fix is the filtering section above — audit which MCP tools the agent has actually called in the last week of transcripts, move every server to a tools.include list of just those, and turn off prompts/resources wrappers you do not use. It is common to cut a registry from 60+ tools to under 15 with zero loss of capability.

3. Auth failures

For stdio servers, auth problems are almost always env problems: the token in the env block is expired, has the wrong scopes, or was pasted with a trailing newline. For remote servers, confirm the endpoint is reachable at all (a plain curl against the URL tells you whether you have a network problem or an auth problem) and that the Authorization header format matches what the provider expects. Two subtle ones: some servers advertise capabilities they do not actually implement, so a resources: true expectation can fail even with valid auth; and paid gateways like the AI2SQL endpoint return a payment-required error rather than an auth error when the key is valid but the plan does not cover API access — read the error body, not just the status code.

Related Guides

Frequently Asked Questions