MCP 客户端

MCP 客户端：连接服务器、注册工具（stdio/SSE 传输）

Native MCP Client

Hermes Agent 内置 MCP 客户端，在启动时连接到 MCP 服务器，发现其工具，并将其作为一级工具供 agent 直接调用。无需桥接 CLI——来自 MCP 服务器的工具与 terminal、read_file 等内置工具一同出现。

使用场景

在以下情况使用：

对于临时的一次性 MCP 工具调用（无需配置任何内容），参见 mcporter skill。

前置条件

安装 MCP SDK：

pip install mcp
# 或使用 uv：
uv pip install mcp

快速入门

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

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

重启 Hermes Agent。启动时它会：

然后可以自然地使用工具——只需让 agent 获取当前时间。

配置参考

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

Stdio 传输（command + args）

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

HTTP 传输（url）

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

所有配置选项

注意：服务器配置必须要有 command（stdio）或 url（HTTP），不能同时有两者。

工作原理

启动时发现

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

工具命名约定

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

mcp_{server_name}_{tool_name}

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

示例：

自动注入

发现后，MCP 工具自动注入到所有 hermes-* 平台工具集（CLI、Discord、Telegram 等）。这意味着 MCP 工具在每次对话中都可用，无需额外配置。

连接生命周期

幂等性

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 子进程。只继承安全的基础变量：

所有其他环境变量（API 密钥、令牌、密钥）被排除——除非你通过 env 配置键明确添加。这防止了意外凭证泄露给不受信任的 MCP 服务器。

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

错误消息中的凭证剥离

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

常见问题

"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'"

常见原因：

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

你的 mcp 包版本不包含 HTTP 客户端支持。升级：

pip install --upgrade mcp

工具不出现

连接持续断开

客户端以指数退避重试最多 5 次（1s、2s、4s、8s、16s，上限 60s）。如果服务器根本不可达，5 次尝试后放弃。检查服务器进程和网络连接。

示例

时间服务器（uvx）

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

注册类似 mcp_time_get_current_time 的工具。

文件系统服务器（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

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

Sampling（服务器发起的 LLM 请求）

Hermes 支持 MCP 的 sampling/createMessage 能力——MCP 服务器可在工具执行期间通过 agent 请求 LLM 完成。这实现了 agent 循环工作流（数据分析、内容生成、决策）。

Sampling 默认启用。按服务器配置：

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

服务器也可以在 sampling 请求中包含 tools 以实现多轮工具增强工作流。max_tool_rounds 配置防止无限工具循环。通过 get_mcp_status() 追踪每个服务器的审计指标（请求数、错误数、token 数、工具使用次数）。

对不受信任的服务器，用 sampling: { enabled: false } 禁用 sampling。

注意事项