Hermes Agent MCP integration

MCP (Model Context Protocol) is an open protocol proposed by Anthropic for standardizing interactions between LLMs and external tools.

Hermes natively supports MCP, allowing integration with any MCP-compatible service such as GitHub, databases, file systems, browser stacks, and internal APIs without modifying core code.

This chapter will dive into MCP's two integration methods, tool filtering strategies, security isolation mechanisms, and common troubleshooting.

What is MCP

MCP solves a practical problem: with each new service integration, the traditional approach requires writing adapter code, defining tool schemas, and handling authentication—every service is one-off work.

MCP standardizes all of this. Hermes can directly integrate with any service that implements the MCP protocol, with no additional development required.

MCP's core role:

Hermes Agent（MCP 客户端）
    │
    ├── stdio ──→ MCP 服务器 A（本地子进程）
    │                  └── 暴露工具：git_commit, git_push...
    │
    ├── HTTP ───→ MCP 服务器 B（远程服务）
    │                  └── 暴露工具：list_issues, create_issue...
    │
    └── HTTP ───→ MCP 服务器 C（远程 OAuth）
                       └── 暴露工具：search_docs, create_page...

Standard installation includes MCP support, no additional steps required. All MCP servers in~/.hermes/config.yamlcentralized configuration in.

MCP is not a proprietary protocol of Hermes—it is open. Servers written for other MCP-supporting tools (such as Claude Code's MCP servers) can be used directly in Hermes, and vice versa.

Two types of MCP servers

Local stdio server

Runs locally as a subprocess, communicating with Hermes via standard input/output (stdin/stdout).

Communication uses the JSON-RPC protocol, with each message separated by a newline character.

Applicable scenarios: tools are installed locally, requiring low-latency access to local resources (file systems, Git repositories, local databases).

The lifecycle of stdio servers is managed by Hermes:

• Session start or/reload-mcpWhen Hermes starts a child process
• When a session ends or a server is disabled, Hermes terminates the child process.
• A crashed child process automatically restarts (with up to 3 retries).

Remote HTTP server

Directly connects to remote MCP endpoints via HTTP requests, supporting multiple authentication methods.

Applicable scenarios: tools are hosted remotely, or your organization already has MCP interfaces.

Comparison of two types

Nous curated MCP directory

Hermes comes with a Nous Research-vetted MCP directory, offering a one-click installation experience.

Browse and install

Open the interactive selector (TUI) to browse all directory entries:

hermes mcp

Other commands:

# 纯文本列表（适合脚本化）
hermes mcp catalog

# 按名称一键安装
hermes mcp install n8n
hermes mcp install github
hermes mcp install linear

The interactive selector shows the current status of each entry:

n8n          available              管理和检查 n8n 工作流
linear       enabled                Linear 问题/项目管理（远程 OAuth）
github       installed (disabled)   GitHub 仓库 + PR 工具
filesystem   installed (enabled)    安全的文件系统操作
postgres     available               PostgreSQL 数据库查询
slack        available               Slack 消息和频道管理

Status description:

Desktop version: view configuration in the settings menu:

View the configuration in the MCP menu on the left of the dashboard:

What happens during installation

One-click installation automatically completes three steps:

1. Configuration guide: prompts you to enter the API Key or guides the OAuth browser authorization flow.
2. Tool detection: connects to the server and retrieves the complete list of tools it exposes.
3. Tool selection: displays the tool list for you to check the tools you want to enable (all selected by default).

The third step (tool selection) is an important security checkpoint—you don't need every tool. For example, if the GitHub server exposes delete_repo and you don't need it, you can uncheck it.

Tool filtering: expose only what you need

Every MCP server supports fine-grained tool filtering. This is a key security mechanism for reducing the Agent's attack surface.

include mode (whitelist)

Only register tools in the list; exclude all others:

exclude mode (blacklist)

Exclude tools in the list; register all others:

Filter rule priority

Disable resources and prompts

In addition to tools, MCP servers may also expose resources and prompts. If you don't need them, you can turn them off:

MCP environment variable isolation

This is the most easily overlooked yet most important design in Hermes' MCP security mechanisms.

The MCP stdio child process receives anFiltered environmentBy default, only passes the following variables:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
以及所有 XDG_* 变量

All other environment variables (API Key, Token, password) are blocked.

Only environment variables explicitly declared in the MCP server configurationenv:Only variables explicitly declared in the block are passed into the child process:

Why is it designed this way? Suppose you have 10 API Keys stored in .env (OpenAI, Anthropic, SerpAPI, Telegram Bot Token...). If an MCP server could read all environment variables, a malicious MCP server tool could steal all credentials. Environment variable isolation ensures it can only see the explicitly declared one.

Error messages are automatically redacted

MCP tool error messages are automatically sanitized before being returned to the LLM—sensitive information (API Key, Token, password) is replaced with[REDACTED]。

This prevents the Agent from accidentally seeing plaintext credentials when analyzing errors.

Manually add an MCP server

Besides one-click installation from the Nous directory, you can also manually add any MCP-compatible server.

hermes mcp configureIt opens an interactive tool selection interface, letting you re-check the tools to enable.

Reload MCP configuration

After modifying the MCP configuration in config.yaml, there's no need to restart the entire Agent:

Common troubleshooting