native-mcp

原生 MCP 客户端

Hermes Agent 内置了 MCP 客户端，可在启动时连接 MCP 服务、发现其工具，并将这些工具作为 Agent 可直接调用的一等工具。无需使用桥接 CLI——MCP 服务中的工具会与 terminal、read_file 等内置工具一同显示。

适用场景

在以下情况下使用：

• 连接 MCP 服务，并在 Hermes Agent 中使用其工具
• 通过 MCP 添加外部能力（文件系统访问、GitHub、数据库、API）
• 运行本地基于 stdio 的 MCP 服务（npx、uvx 或任何命令）
• 连接远程 HTTP/StreamableHTTP MCP 服务
• 自动发现 MCP 工具，并让它们在每次对话中都可用

如果要在终端中临时调用 MCP 工具，而不进行任何配置，请改用 mcporter 技能。

前置条件

• mcp Python 包——可选依赖；使用 pip install mcp 安装。如果未安装，MCP 支持将被静默禁用。
• Node.js——运行基于 npx 的 MCP 服务（大多数社区服务）所必需
• uv——运行基于 uvx 的 MCP 服务（基于 Python 的服务）所必需

安装 MCP SDK：

pip install mcp
# or, if using uv:
uv pip install mcp

快速开始

在 ~/.hermes/config.yaml 的 mcp_servers 键下添加 MCP 服务：

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

重启 Hermes Agent。启动时，它将：

1. 连接到服务
2. 发现可用工具
3. 使用前缀 mcp_time_* 注册这些工具
4. 将这些工具注入所有平台工具集

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

配置参考

mcp_servers 下的每个条目都包含一个服务名称及其配置。传输类型有两种：stdio（基于命令）和 HTTP（基于 URL）。

Stdio 传输（command + args）

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

HTTP 传输（url）

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

所有配置选项

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

注意：服务配置必须包含 command（stdio）或 url（HTTP）之一，不能同时包含两者。

工作原理

启动时发现

Hermes Agent 启动时，会在工具初始化期间调用 discover_mcp_tools()：

1. 从 ~/.hermes/config.yaml 读取 mcp_servers
2. 为每个服务在专用后台事件循环中启动连接
3. 初始化 MCP 会话并调用 list_tools()，发现可用工具
4. 在 Hermes 工具注册表中注册每个工具

工具命名约定

MCP 工具按以下命名模式注册：

mcp_{server_name}_{tool_name}

为了兼容大模型 API，名称中的连字符和句点会替换为下划线。

示例：

• 服务 filesystem，工具 read_file → mcp_filesystem_read_file
• 服务 github，工具 list-issues → mcp_github_list_issues
• 服务 my-api，工具 fetch.data → mcp_my_api_fetch_data

自动注入

发现完成后，MCP 工具会自动注入所有 hermes-* 平台工具集（CLI、Discord、Telegram 等）。因此，无需任何额外配置，MCP 工具就能在每次对话中使用。

连接生命周期

• 每个服务都作为长期运行的 asyncio Task，在后台守护线程中运行
• 连接会在 Agent 进程的整个生命周期内保持
• 如果连接断开，将自动通过指数退避进行重连（最多重试 5 次，最长退避时间为 60s）
• Agent 关闭时，所有连接都会正常关闭

幂等性

discover_mcp_tools() 是幂等的——多次调用时，只会连接尚未连接的服务。连接失败的服务会在后续调用时重试。

传输类型

Stdio 传输

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

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

子进程会继承经过筛选的环境（参见下文的“安全”部分），以及你在 env 中指定的变量。

HTTP / StreamableHTTP 传输

适用于远程或共享 MCP 服务。要求 mcp 包包含 HTTP 客户端支持（mcp.client.streamable_http）。

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

如果你安装的 mcp 版本不支持 HTTP，连接该服务时会触发 ImportError，其他服务仍会正常运行。

安全

环境变量筛选

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

• PATH、HOME、USER、LANG、LC_ALL、TERM、SHELL、TMPDIR
• 所有 XDG_* 变量

除非你通过 env 配置项明确添加，否则所有其他环境变量（API 密钥、令牌、机密信息）都会被排除。这可以防止凭据意外泄露给不受信任的 MCP 服务。

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

错误消息中的凭据剥离

如果 MCP 工具调用失败，在向大模型显示错误消息之前，系统会自动对其中类似凭据的内容进行脱敏。涵盖以下内容：

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

故障排查

“MCP SDK not available -- skipping MCP tool discovery”

未安装 mcp Python 包。请安装：

pip install mcp

“No MCP servers configured”

~/.hermes/config.yaml 中没有 mcp_servers 键，或者其值为空。请至少添加一个服务。

“Failed to connect to MCP server 'X'”

常见原因：

• 找不到命令：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 包版本不包含 HTTP 客户端支持。请升级：

pip install --upgrade mcp

未显示工具

• 检查服务是否列在 mcp_servers 下（而不是 mcp 或 servers）
• 确保 YAML 缩进正确
• 查看 Hermes Agent 启动日志中的连接消息
• 工具名称带有 mcp_{server}_{tool} 前缀——请查找此模式

连接持续断开

客户端最多重试 5 次，并采用指数退避（1s、2s、4s、8s、16s，最长为 60s）。如果服务根本无法访问，重试 5 次后就会放弃。请检查服务进程和网络连接。

示例

Time 服务（uvx）

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

注册的工具包括 mcp_time_get_current_time。

Filesystem 服务（npx）

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 服务

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 等。

远程 HTTP 服务

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

多个服务

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

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

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

Hermes 支持 MCP 的 sampling/createMessage 功能——MCP 服务可以在工具执行期间，通过 Agent 请求 LLM 补全。这支持 Agent 参与其中的工作流（数据分析、内容生成、决策）。

采样默认已启用。可按服务进行配置：

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

服务还可以在采样请求中包含 tools，以支持多轮工具增强工作流。max_tool_rounds 配置可防止工具陷入无限循环。每个服务的审计指标（请求数、错误数、令牌数、工具使用次数）通过 get_mcp_status() 跟踪。

对于不可信的服务，可通过 sampling: { enabled: false } 禁用采样。

注意事项

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