native-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Native MCP Client

原生MCP客户端

Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like

terminal

read_file

, etc.

Hermes Agent 内置了一个MCP客户端，在启动时连接到MCP服务器，发现其工具，并将这些工具作为Agent可直接调用的一等工具提供。无需桥接CLI——来自MCP服务器的工具会与

terminal

、

read_file

等内置工具一同显示。

When to Use

使用场景

Use this whenever you want to:

Connect to MCP servers and use their tools from within Hermes Agent
Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
Run local stdio-based MCP servers (npx, uvx, or any command)
Connect to remote HTTP/StreamableHTTP MCP servers
Have MCP tools auto-discovered and available in every conversation

For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the

mcporter

skill instead.

在以下场景中使用本功能：

连接到MCP服务器并在Hermes Agent内使用其工具
通过MCP添加外部功能（文件系统访问、GitHub、数据库、API）
运行基于本地stdio的MCP服务器（npx、uvx或任意命令）
连接到远程HTTP/StreamableHTTP MCP服务器
让MCP工具自动被发现并在所有对话中可用

如果需要在终端中临时调用单次MCP工具而无需任何配置，请使用

mcporter

技能。

Prerequisites

前置条件

mcp Python package -- optional dependency; install with
```
pip install mcp
```
. If not installed, MCP support is silently disabled.
Node.js -- required for
```
npx
```
-based MCP servers (most community servers)
uv -- required for
```
uvx
```
-based MCP servers (Python-based servers)

Install the MCP SDK:

bash

pip install mcp

mcp Python包 -- 可选依赖；使用
```
pip install mcp
```
安装。若未安装，MCP支持会被静默禁用。
Node.js -- 运行基于
```
npx
```
的MCP服务器（大多数社区服务器）所需
uv -- 运行基于
```
uvx
```
的MCP服务器（Python类服务器）所需

安装MCP SDK：

bash

pip install mcp

or, if using uv:

或使用uv：

uv pip install mcp

undefined

uv pip install mcp

undefined

Quick Start

快速开始

Add MCP servers to

~/.hermes/config.yaml

under the

mcp_servers

key:

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Restart Hermes Agent. On startup it will:

Connect to the server
Discover available tools
Register them with the prefix
```
mcp_time_*
```
Inject them into all platform toolsets

You can then use the tools naturally -- just ask the agent to get the current time.

在

~/.hermes/config.yaml

的

mcp_servers

键下添加MCP服务器：

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

重启Hermes Agent。启动时它会：

连接到服务器
发现可用工具
以
```
mcp_time_*
```
为前缀注册这些工具
将它们注入到所有平台工具集中

之后你就可以自然地使用这些工具——只需让Agent获取当前时间即可。

Configuration Reference

配置参考

Each entry under

mcp_servers

is a server name mapped to its config. There are two transport types: stdio (command-based) and HTTP (url-based).

mcp_servers

下的每个条目都是一个服务器名称与其配置的映射。有两种传输类型：stdio（基于命令）和HTTP（基于URL）。

Stdio Transport (command + args)

Stdio传输（command + args）

yaml

mcp_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

yaml

mcp_servers:
  server_name:
    command: "npx"             # （必填）要运行的可执行文件
    args: ["-y", "pkg-name"]   # （可选）命令参数，默认值：[]
    env:                       # （可选）子进程的环境变量
      SOME_API_KEY: "value"
    timeout: 120               # （可选）每次工具调用的超时时间（秒），默认值：120
    connect_timeout: 60        # （可选）初始连接超时时间（秒），默认值：60

HTTP Transport (url)

HTTP传输（url）

yaml

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer sk-..."
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

yaml

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # （必填）服务器URL
    headers:                                     # （可选）HTTP请求头
      Authorization: "Bearer sk-..."
    timeout: 180               # （可选）每次工具调用的超时时间（秒），默认值：120
    connect_timeout: 60        # （可选）初始连接超时时间（秒），默认值：60

All Config Options

所有配置选项

Option	Type	Default	Description
`command`	string	--	Executable to run (stdio transport, required)
`args`	list	`[]`	Arguments passed to the command
`env`	dict	`{}`	Extra environment variables for the subprocess
`url`	string	--	Server URL (HTTP transport, required)
`headers`	dict	`{}`	HTTP headers sent with every request
`timeout`	int	`120`	Per-tool-call timeout in seconds
`connect_timeout`	int	`60`	Timeout for initial connection and discovery

Note: A server config must have either

command

(stdio) or

url

(HTTP), not both.

选项	类型	默认值	描述
`command`	字符串	--	要运行的可执行文件（stdio传输，必填）
`args`	列表	`[]`	传递给命令的参数
`env`	字典	`{}`	子进程的额外环境变量
`url`	字符串	--	服务器URL（HTTP传输，必填）
`headers`	字典	`{}`	随每个请求发送的HTTP请求头
`timeout`	整数	`120`	每次工具调用的超时时间（秒）
`connect_timeout`	整数	`60`	初始连接和发现的超时时间

注意：服务器配置必须包含

command

（stdio）或

url

（HTTP）中的一个，不能同时包含两者。

How It Works

工作原理

Startup Discovery

启动时发现

When Hermes Agent starts,

discover_mcp_tools()

is called during tool initialization:

Reads
```
mcp_servers
```
from
```
~/.hermes/config.yaml
```
For each server, spawns a connection in a dedicated background event loop
Initializes the MCP session and calls
```
list_tools()
```
to discover available tools
Registers each tool in the Hermes tool registry

当Hermes Agent启动时，

discover_mcp_tools()

会在工具初始化阶段被调用：

从
```
~/.hermes/config.yaml
```
读取
```
mcp_servers
```
配置
为每个服务器在专用的后台事件循环中建立连接
初始化MCP会话并调用
```
list_tools()
```
发现可用工具
在Hermes工具注册表中注册每个工具

Tool Naming Convention

工具命名规则

MCP tools are registered with the naming pattern:

mcp_{server_name}_{tool_name}

Hyphens and dots in names are replaced with underscores for LLM API compatibility.

Examples:

Server

filesystem

, tool

read_file

→

mcp_filesystem_read_file

Server
```
github
```
, tool
```
list-issues
```
→
```
mcp_github_list_issues
```
Server
```
my-api
```
, tool
```
fetch.data
```
→
```
mcp_my_api_fetch_data
```

MCP工具会按照以下模式注册：

mcp_{server_name}_{tool_name}

名称中的连字符和点会被替换为下划线，以兼容LLM API。

示例：

服务器

filesystem

，工具

read_file

→

mcp_filesystem_read_file

服务器
```
github
```
，工具
```
list-issues
```
→
```
mcp_github_list_issues
```
服务器
```
my-api
```
，工具
```
fetch.data
```
→
```
mcp_my_api_fetch_data
```

Auto-Injection

自动注入

After discovery, MCP tools are automatically injected into all

hermes-*

platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.

发现完成后，MCP工具会自动注入到所有

hermes-*

平台工具集（CLI、Discord、Telegram等）中。这意味着无需额外配置，MCP工具在所有对话中都可用。

Connection Lifecycle

连接生命周期

Each server runs as a long-lived asyncio Task in a background daemon thread
Connections persist for the lifetime of the agent process
If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
On agent shutdown, all connections are gracefully closed

每个服务器作为长期运行的asyncio任务在后台守护线程中运行
连接会在Agent进程的整个生命周期内保持
如果连接断开，会自动触发指数退避重连（最多5次重试，最大退避时间60秒）
Agent关闭时，所有连接会被优雅关闭

Idempotency

幂等性

discover_mcp_tools()

is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.

discover_mcp_tools()

是幂等的——多次调用只会连接尚未连接的服务器。连接失败的服务器会在后续调用中重试。

Transport Types

传输类型

Stdio Transport

Stdio传输

The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.

yaml

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

The subprocess inherits a filtered environment (see Security section below) plus any variables you specify in

env

最常用的传输方式。Hermes将MCP服务器作为子进程启动，并通过stdin/stdout进行通信。

yaml

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

子进程会继承经过过滤的环境（见下文安全部分）以及你在

env

中指定的任何变量。

HTTP / StreamableHTTP Transport

HTTP / StreamableHTTP传输

For remote or shared MCP servers. Requires the

mcp

package to include HTTP client support (

mcp.client.streamable_http

yaml

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."

If HTTP support is not available in your installed

mcp

version, the server will fail with an ImportError and other servers will continue normally.

适用于远程或共享MCP服务器。要求

mcp

包包含HTTP客户端支持（

mcp.client.streamable_http

）。

yaml

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer sk-..."

如果你的

mcp

版本不支持HTTP客户端，该服务器会因ImportError失败，但其他服务器会正常运行。

Security

安全说明

Environment Variable Filtering

环境变量过滤

For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:

```
PATH
```
,
```
HOME
```
,
```
USER
```
,
```
LANG
```
,
```
LC_ALL
```
,
```
TERM
```
,
```
SHELL
```
,
```
TMPDIR
```
Any
```
XDG_*
```
variables

All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the

env

config key. This prevents accidental credential leakage to untrusted MCP servers.

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # Only this token is passed to the subprocess
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

对于stdio服务器，Hermes不会将完整的shell环境传递给MCP子进程。仅会继承安全的基线变量：

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

所有其他环境变量（API密钥、令牌、机密）都会被排除，除非你通过

env

配置键显式添加。这可以防止意外将凭据泄露给不可信的MCP服务器。

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # 只有此令牌会被传递给子进程
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

Credential Stripping in Error Messages

错误消息中的凭据剥离

If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:

GitHub PATs (
```
ghp_...
```
)
OpenAI-style keys (
```
sk-...
```
)
Bearer tokens
Generic
```
token=
```
,
```
key=
```
,
```
API_KEY=
```
,
```
password=
```
,
```
secret=
```
patterns

如果MCP工具调用失败，错误消息中任何类似凭据的模式都会被自动编辑后再显示给LLM。这包括：

GitHub PAT（
```
ghp_...
```
）
OpenAI风格密钥（
```
sk-...
```
）
Bearer令牌
通用的
```
token=
```
、
```
key=
```
、
```
API_KEY=
```
、
```
password=
```
、
```
secret=
```
模式

Troubleshooting

故障排除

"MCP SDK not available -- skipping MCP tool discovery"

"MCP SDK不可用——跳过MCP工具发现"

The

mcp

Python package is not installed. Install it:

bash

pip install mcp

未安装

mcp

Python包。请安装：

bash

pip install mcp

"No MCP servers configured"

"未配置MCP服务器"

mcp_servers

key in

~/.hermes/config.yaml

, or it's empty. Add at least one server.

~/.hermes/config.yaml

中没有

mcp_servers

键，或者该键为空。请至少添加一个服务器。

"Failed to connect to MCP server 'X'"

"无法连接到MCP服务器'X'"

Common causes:

Command not found: The
```
command
```
binary isn't on PATH. Ensure
```
npx
```
,
```
uvx
```
, or the relevant command is installed.
Package not found: For npx servers, the npm package may not exist or may need
```
-y
```
in args to auto-install.
Timeout: The server took too long to start. Increase
```
connect_timeout
```
.
Port conflict: For HTTP servers, the URL may be unreachable.

常见原因：

命令未找到：
```
command
```
指定的可执行文件不在PATH中。确保已安装
```
npx
```
、
```
uvx
```
或相关命令。
包未找到：对于npx服务器，npm包可能不存在，或者需要在args中添加
```
-y
```
以自动安装。
超时：服务器启动时间过长。增加
```
connect_timeout
```
的值。
端口冲突：对于HTTP服务器，URL可能无法访问。

"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"

"MCP服务器'X'需要HTTP传输，但mcp.client.streamable_http不可用"

Your

mcp

package version doesn't include HTTP client support. Upgrade:

bash

pip install --upgrade mcp

你的

mcp

包版本不包含HTTP客户端支持。请升级：

bash

pip install --upgrade mcp

Tools not appearing

工具未显示

Check that the server is listed under
```
mcp_servers
```
(not
```
mcp
```
or
```
servers
```
)
Ensure the YAML indentation is correct
Look at Hermes Agent startup logs for connection messages
Tool names are prefixed with
```
mcp_{server}_{tool}
```
-- look for that pattern

检查服务器是否在
```
mcp_servers
```
下配置（不是
```
mcp
```
或
```
servers
```
）
确保YAML缩进正确
查看Hermes Agent启动日志中的连接消息
工具名称以
```
mcp_{server}_{tool}
```
为前缀——查找该模式

Connection keeps dropping

连接持续断开

The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.

客户端最多重试5次，采用指数退避策略（1秒、2秒、4秒、8秒、16秒，上限60秒）。如果服务器根本无法访问，5次尝试后会放弃。检查服务器进程和网络连接。

Examples

示例

Time Server (uvx)

时间服务器（uvx）

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Registers tools like

mcp_time_get_current_time

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

会注册

mcp_time_get_current_time

等工具。

Filesystem Server (npx)

文件系统服务器（npx）

yaml

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

Registers tools like

mcp_filesystem_read_file

mcp_filesystem_write_file

mcp_filesystem_list_directory

yaml

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

会注册

mcp_filesystem_read_file

、

mcp_filesystem_write_file

、

mcp_filesystem_list_directory

等工具。

GitHub Server with Authentication

带认证的GitHub服务器

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    timeout: 60

Registers tools like

mcp_github_list_issues

mcp_github_create_pull_request

, etc.

yaml

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    timeout: 60

会注册

mcp_github_list_issues

、

mcp_github_create_pull_request

等工具。

Remote HTTP Server

远程HTTP服务器

yaml

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

yaml

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

Multiple Servers

多服务器配置

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.

yaml

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

所有服务器的工具都会被注册并同时可用。每个服务器的工具都会以其名称为前缀，避免冲突。

Sampling (Server-Initiated LLM Requests)

采样（服务器发起的LLM请求）

Hermes supports MCP's

sampling/createMessage

capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).

Sampling is enabled by default. Configure per server:

yaml

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true           # default: true
      model: "gemini-3-flash" # model override (optional)
      max_tokens_cap: 4096    # max tokens per request
      timeout: 30             # LLM call timeout (seconds)
      max_rpm: 10             # max requests per minute
      allowed_models: []      # model whitelist (empty = all)
      max_tool_rounds: 5      # tool loop limit (0 = disable)
      log_level: "info"       # audit verbosity

Servers can also include

tools

in sampling requests for multi-turn tool-augmented workflows. The

max_tool_rounds

config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via

get_mcp_status()

Disable sampling for untrusted servers with

sampling: { enabled: false }

Hermes支持MCP的

sampling/createMessage

功能——MCP服务器可以在工具执行期间通过Agent请求LLM补全。这支持Agent在环内的工作流（数据分析、内容生成、决策制定）。

采样默认启用。可按服务器配置：

yaml

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true           # 默认值：true
      model: "gemini-3-flash" # 模型覆盖（可选）
      max_tokens_cap: 4096    # 每次请求的最大令牌数
      timeout: 30             # LLM调用超时时间（秒）
      max_rpm: 10             # 每分钟最大请求数
      allowed_models: []      # 模型白名单（空表示允许所有）
      max_tool_rounds: 5      # 工具循环限制（0表示禁用）
      log_level: "info"       # 审计日志级别

服务器还可以在采样请求中包含

tools

，以支持多轮工具增强工作流。

max_tool_rounds

配置可防止无限工具循环。每个服务器的审计指标（请求数、错误数、令牌数、工具使用次数）可通过

get_mcp_status()

跟踪。

对于不可信服务器，可使用

sampling: { enabled: false }

禁用采样。

Notes

注意事项

MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
Tool results are returned as JSON with either
```
{"result": "..."}
```
or
```
{"error": "..."}
```
The native MCP client is independent of
```
mcporter
```
-- you can use both simultaneously
Server connections are persistent and shared across all conversations in the same agent process
Adding or removing servers requires restarting the agent (no hot-reload currently)

从Agent的角度看，MCP工具是同步调用的，但会在专用的后台事件循环中异步运行
工具结果以JSON格式返回，格式为
```
{"result": "..."}
```
或
```
{"error": "..."}
```
原生MCP客户端独立于
```
mcporter
```
——你可以同时使用两者
服务器连接是持久的，并在同一Agent进程的所有对话中共享
添加或移除服务器需要重启Agent（目前不支持热重载）