MCP 配置参考

本页是 MCP 主文档的精简参考页。

如需概念性说明，请参阅：

• MCP (Model Context Protocol)
• Use MCP with Hermes

根配置结构

mcp_servers:
  <server_name>:
    command: "..."      # stdio servers
    args: []
    env: {}

    # OR
    url: "..."          # HTTP servers
    headers: {}

    enabled: true
    timeout: 120
    connect_timeout: 60
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

服务器级配置键

Key	Type	Applies to	Meaning
command	string	stdio	要启动的可执行命令
args	list	stdio	子进程参数
env	mapping	stdio	传给子进程的环境变量
url	string	HTTP	远程 MCP 端点
headers	mapping	HTTP	向远端服务器请求时附带的 headers
enabled	bool	both	为 false 时完全跳过该服务器
timeout	number	both	工具调用超时
connect_timeout	number	both	初始连接超时
tools	mapping	both	过滤与实用工具策略
auth	string	HTTP	认证方式。设为 oauth 可启用带 PKCE 的 OAuth 2.1
sampling	mapping	both	服务器发起 LLM 请求的策略（见 MCP 指南）

tools 策略键

Key	Type	Meaning
include	string or list	对服务器原生 MCP 工具做白名单
exclude	string or list	对服务器原生 MCP 工具做黑名单
resources	bool-like	启用 / 禁用 list_resources 与 read_resource
prompts	bool-like	启用 / 禁用 list_prompts 与 get_prompt

过滤语义

include

如果设置了 include，那么只有这些服务器原生 MCP 工具会被注册。

tools:
  include: [create_issue, list_issues]

exclude

如果设置了 exclude 且没有设置 include，则除了这些名字外，其他服务器原生 MCP 工具都会被注册。

tools:
  exclude: [delete_customer]

优先级

如果两者同时设置，以 include 为准。

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

结果：

• create_issue 依然允许
• delete_issue 会被忽略，因为 include 优先级更高

实用工具策略

Hermes 可能会为每个 MCP 服务器注册以下实用包装工具：

Resources:

• list_resources
• read_resource

Prompts:

• list_prompts
• get_prompt

禁用 resources

tools:
  resources: false

禁用 prompts

tools:
  prompts: false

基于能力的注册

即使你把 resources: true 或 prompts: true 打开，Hermes 也只会在当前 MCP 会话真的暴露了相应能力时，才注册这些实用工具。

所以出现下面这种情况是正常的：

• 你启用了 prompts
• 但没有任何 prompt 相关工具出现
• 因为该服务器根本不支持 prompts

enabled: false

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

行为：

• 不会尝试连接
• 不会做 discovery
• 不会注册任何工具
• 配置依然保留，后续可随时重新启用

空结果行为

如果过滤规则把所有服务器原生工具都移除了，并且也没有注册任何实用工具，那么 Hermes 不会为这台服务器创建一个空的 MCP 运行时 toolset。

示例配置

安全的 GitHub 白名单

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

Stripe 黑名单

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

仅 resources 的文档服务器

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

重载配置

修改 MCP 配置后，使用下面的命令重载服务器：

/reload-mcp

工具命名

服务器原生 MCP 工具会变成：

mcp_<server>_<tool>

例如：

• mcp_github_create_issue
• mcp_filesystem_read_file
• mcp_my_api_query_data

实用工具也遵循同样的前缀规则：

• mcp_<server>_list_resources
• mcp_<server>_read_resource
• mcp_<server>_list_prompts
• mcp_<server>_get_prompt

名称清洗

服务器名和工具名里的连字符（-）与点号（.）在注册前都会被替换为下划线，以确保它们是适用于 LLM function calling API 的合法标识符。

例如，服务器名为 my-api，暴露的工具叫 list-items.v2，最终会变成：

mcp_my_api_list_items_v2

编写 include / exclude 过滤规则时请注意：要使用 原始 MCP 工具名（包含连字符和点号），而不是清洗后的名字。

OAuth 2.1 认证

对于需要 OAuth 的 HTTP 服务器，在该服务器配置上设置 auth: oauth：

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

行为：

• Hermes 使用 MCP SDK 的 OAuth 2.1 PKCE 流程（metadata discovery、动态客户端注册、token 交换与刷新）
• 第一次连接时会打开浏览器让你授权
• token 会持久化到 ~/.hermes/mcp-tokens/<server>.json，并在后续会话中复用
• token 刷新是自动的；只有刷新失败时才需要重新授权
• 仅适用于 HTTP / StreamableHTTP 传输（即基于 url 的服务器）