MCP 集成实战

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：crates/cheng-nodes/src/nodes/builtin/tools/mcp_hub.rs、crates/cheng-mcp/src/lib.rs、crates/cheng-core/src/domain/mcp_server.rs

ChengOS 在 MCP 上是双向的：

本页主要讲客户端，因为「接入 MCP Server」通常指的就是它。

MCP Hub 节点

tools/mcp_hub 是一个节点管理多个 MCP 服务。把它连到智能体的 tools 端口，智能体就获得了这些服务暴露的全部工具——受下文可见性规则约束。

它的指导原则是配置优先：默认情况下节点只返回服务器状态，只有当你显式发现或调用时才会发出请求。把节点丢到画布上并不会触发任何连接。

传输方式

两者互斥：带 command 的服务器配置是 stdio，带 url 的是 HTTP。

每个服务器条目还有 enabled、独立的 timeout，以及 long_running 标志。long_running 会保持一个常驻会话——stdio 是常驻子进程，否则是常驻 HTTP 会话——而不是每次调用都重连。启动开销大的服务器该开它；节点会缓存并复用该会话。

用凭证，别写字面量

不要把 API 密钥粘进服务器配置。把 utils/credential 节点的 env_vars 输出连到 Hub 的 env_vars 输入，然后用 ${env:KEY} 引用。

占位符在所有字符串字段中展开——url、authorization、headers、args 和 env。当同一个键两边都定义时，凭证节点的值优先于系统进程环境变量，因此工作流自己的凭证不会被服务器环境里恰好存在的东西覆盖掉。

可见性控制

把每个服务的每个工具都暴露给模型通常是错的：既烧上下文，又默认把破坏性操作交到模型手上。Hub 把可见（模型能看到）和可调用（模型可以调）分开。

推荐的结构化写法：

{
  "servers": {
    "my-server": { "visible": true, "callable": true },
    "*":         { "visible": true, "callable": true }
  },
  "tools": {
    "my-server:search": { "visible": true,  "callable": true  },
    "my-server:delete": { "visible": false, "callable": false },
    "*":                { "visible": true,  "callable": true  }
  }
}

另有一种以 server:tool 为键的扁平兼容写法。两者同时存在时，visibility_config 压过 tool_visibility。

匹配从最具体开始：

1. server:tool     精确匹配
2. server:*        服务器通配
3. *:tool          工具名通配
4. *               全局默认

值得采用的模式是：把 * 设为可见且可调用，然后按名字显式禁掉那些破坏性工具。visible: false 的工具同时也不占用上下文。

调用工具

tool_name、arguments 和 discover_only 可由 LLM 填写。服务器清单、可见性配置和凭证属于模型永远看不到的画布静态配置——这正是模型无法修改自己权限的原因。

输出是单一的 result 端口，携带摘要、各服务器状态、发现到的工具，以及可能的工具调用输出，因此节点的形状在配置态、发现态和调用态之间不会改变。

多模态结果

MCP 工具返回的可以不止文本，Hub 会在 content_parts 中完整保留：

{"type":"text","text":"..."}
{"type":"image","mimeType":"image/png","data":"base64..."}
{"type":"resource","resource":{"uri":"...","text":"...","mimeType":"..."}}

因此一个会画图的 MCP 工具，其结果能以图片形式抵达具备视觉能力的模型，而不是被当成附件丢掉。

把工作流发布为 MCP 服务

另一个方向。cheng-mcp 提供两种服务模式：

两者都走 Streamable HTTP。stdio 模式：

cargo run -p cheng-mcp -- --stdio

已发布的工作流会得到一条 McpServer 记录，把它绑定到网关端口、节点通过心跳上报的内部 URL，以及写进 JSON manifest 的公开网关 URL。发布者拥有相应的认证令牌。

排查

下一步

• 工具发现与 Tool Hub——智能体如何与内置工具一并看待这些工具。
• ReAct 智能体指南——调用它们的那个智能体。
• Skills 体系概览——另一种打包能力的方式。