好奇心花园🪴

搜索

SearchSearch

最近的笔记

MCP 配置参考

2026年5月24日6分钟阅读

MCP 配置参考（MCP Config Reference）

本文是 MCP 主文档的紧凑参考伴侣。

概念性指导请参阅：

根配置结构（Root config shape）

mcp_servers:
  <server_name>:
    command: "..."      # stdio 服务器
    args: []
    env: {}
 
    # 或者
    url: "..."          # HTTP 服务器
    headers: {}
 
    enabled: true
    timeout: 120
    connect_timeout: 60
    supports_parallel_tool_calls: false
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

服务器键（Server keys）

键类型适用于含义
commandstringstdio要启动的可执行文件
argsliststdio子进程的参数
envmappingstdio传递给子进程的环境变量
urlstringHTTP远程 MCP 端点
headersmappingHTTP远程服务器请求的头部
enabledbool两者设为 false 时完全跳过该服务器
timeoutnumber两者工具调用超时（秒）
connect_timeoutnumber两者初始连接超时（秒）
supports_parallel_tool_callsbool两者允许此服务器的工具并发运行
toolsmapping两者过滤和实用工具策略
authstringHTTP认证方式。设为 oauth 启用 OAuth 2.1 with PKCE
samplingmapping两者服务器发起的 LLM 请求策略（参见 MCP 指南）

tools 策略键（Tools policy keys）

键类型含义
includestring 或 list白名单：服务器原生 MCP 工具
excludestring 或 list黑名单：服务器原生 MCP 工具
resourcesbool-like启用/禁用 list_resources + read_resource
promptsbool-like启用/禁用 list_prompts + get_prompt

过滤语义（Filtering semantics）

include

如果设置了 include，则只注册这些服务器原生 MCP 工具。

tools:
  include: [create_issue, list_issues]

exclude

如果设置了 exclude 而未设置 include，则注册除这些名称外的所有服务器原生 MCP 工具。

tools:
  exclude: [delete_customer]

优先级（Precedence）

如果两者都设置，include 优先。

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

结果：

  • create_issue 仍被允许
  • delete_issue 被忽略，因为 include 优先

实用工具策略（Utility-tool policy）

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

资源（Resources）：

  • list_resources
  • read_resource

提示（Prompts）：

  • list_prompts
  • get_prompt

禁用资源（Disable resources）

tools:
  resources: false

禁用提示（Disable prompts）

tools:
  prompts: false

能力感知注册（Capability-aware registration）

即使设置了 resources: true 或 prompts: true，只有当 MCP 会话实际暴露了相应能力时，Hermes 才会注册这些实用工具。

所以以下情况是正常的：

  • 您启用了提示（prompts）
  • 但没有出现提示实用工具
  • 因为该服务器不支持提示

enabled: false

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

行为：

  • 不尝试连接
  • 不进行发现
  • 不注册工具
  • 配置保留在原地供以后重用

空结果行为（Empty result behavior）

如果过滤移除了所有服务器原生工具且没有注册任何实用工具，Hermes 不会为该服务器创建一个空的 MCP 运行时工具集。

配置示例（Example configs）

安全的 GitHub 白名单（Safe GitHub allowlist）

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 黑名单（Stripe blacklist）

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

仅资源文档服务器（Resource-only docs server）

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

重新加载配置（Reloading config）

更改 MCP 配置后，使用以下命令重新加载服务器：

/reload-mcp

工具命名（Tool naming）

服务器原生 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

名称规范化（Name sanitization）

服务器名称和工具名称中的连字符（-）和点（.）在注册前会被替换为下划线。这确保工具名称对于 LLM 函数调用 API 是有效的标识符。

例如，一个名为 my-api 的服务器暴露了一个名为 list-items.v2 的工具，变为：

mcp_my_api_list_items_v2

在编写 include / exclude 过滤器时请记住这一点——使用 原始 MCP 工具名称（含连字符/点），而非规范化后的版本。

OAuth 2.1 认证（OAuth 2.1 authentication）

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

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

行为：

  • Hermes 使用 MCP SDK 的 OAuth 2.1 PKCE 流程（元数据发现、动态客户端注册、令牌交换和刷新）
  • 首次连接时，会打开浏览器窗口进行授权
  • 令牌持久化到 ~/.hermes/mcp-tokens/<server>.json 并在会话间复用
  • 令牌刷新自动进行；仅在刷新失败时重新授权
  • 仅适用于 HTTP/StreamableHTTP 传输（基于 url 的服务器）

关系图谱

反向链接