跳到主要内容

本页总览

本页是主 MCP 文档的简明参考手册。

概念说明请参阅：

• MCP（Model Context Protocol）
• 在 Hermes 中使用 MCP

根配置结构 ​

mcp_servers:

  <server_name>:

    command: "..."      # stdio servers

    args: []

    env: {}

    # OR

    url: "..."          # HTTP servers

    headers: {}

    enabled: true

    timeout: 120

    connect_timeout: 60

    supports_parallel_tool_calls: false

    tools:

      include: []

      exclude: []

      resources: true

      prompts: true

服务器键 ​

键	类型	适用范围	含义
command	string	stdio	要启动的可执行文件
args	list	stdio	子进程的参数
env	mapping	stdio	传递给子进程的环境变量
url	string	HTTP	远程 MCP 端点
headers	mapping	HTTP	远程服务器请求的请求头
enabled	bool	两者	为 false 时完全跳过该服务器
timeout	number	两者	工具调用超时时间
connect_timeout	number	两者	初始连接超时时间
supports_parallel_tool_calls	bool	两者	允许该服务器的工具并发执行
tools	mapping	两者	过滤及工具策略
auth	string	HTTP	认证方式。设为 oauth 可启用带 PKCE 的 OAuth 2.1
sampling	mapping	两者	服务器发起的 LLM 请求策略（参见 MCP 指南）

tools 策略键 ​

键	类型	含义
include	string 或 list	白名单：指定允许注册的服务器原生 MCP 工具
exclude	string 或 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: "

    enabled: false

行为：

• 不发起连接
• 不进行服务发现
• 不注册工具
• 配置保留，供后续复用

空结果行为 ​

若过滤后服务器原生工具全部被移除，且没有工具被注册，Hermes 不会为该服务器创建空的 MCP 运行时工具集。

配置示例 ​

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

    headers:

      Authorization: "Bearer ***"

    tools:

      exclude: [delete_customer, refund_payment]

仅资源的文档服务器 ​

mcp_servers:

  docs:

    url: "

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

    auth: oauth

行为：

• Hermes 使用 MCP SDK 的 OAuth 2.1 PKCE 流程（元数据发现、动态客户端注册、token 交换及刷新）

• 首次连接时，浏览器窗口将打开以完成授权

• Token 持久化至 ~/.hermes/mcp-tokens/<server>.json，跨会话复用

• Token 刷新自动进行；仅在刷新失败时才需重新授权

• 仅适用于 HTTP/StreamableHTTP 传输（基于 url 的服务器）

• 根配置结构

• 服务器键

• tools 策略键

• 过滤语义

  • include
  • exclude
  • 优先级

• 工具策略

  • 禁用 resources
  • 禁用 prompts
  • 能力感知注册

• enabled: false

• 空结果行为

• 配置示例

  • GitHub 安全白名单
  • Stripe 黑名单
  • 仅资源的文档服务器

• 重新加载配置

• 工具命名

  • 名称规范化

• OAuth 2.1 认证