16. MCP：外部工具如何接进 OpenClaw

这篇解决什么问题

MCP 让外部工具以统一协议接入 Agent。

OpenClaw 源码里有独立的：

src/mcp/
src/config/mcp-config-normalize.ts
src/config/mcp-config.test.ts
src/agents/agent-bundle-mcp-*.ts

说明 MCP 不是附属脚本，而是 runtime 需要处理的能力。

MCP 在 OpenClaw 里解决什么

可以理解成：

配置 MCP server
→ 连接或启动 server
→ 发现 tools
→ materialize 到 agent bundle
→ 纳入工具策略
→ Agent 调用外部工具

最终还是进入 Agent Runtime 的工具面。

为什么会有 agent-bundle-mcp

OpenClaw 的 Agent Runtime 要构造一个 agent bundle：模型、上下文、tools、resources、skills 等。

MCP tools 需要被 materialize 进这个 bundle，模型才能看到并调用。

所以你会看到：

agent-bundle-mcp-materialize.ts
agent-bundle-mcp-runtime.ts
agent-bundle-mcp-tools.ts
agent-bundle-mcp-types.ts

这些文件名已经说明了主线。

配置归一化很重要

MCP 配置可能来自不同地方、不同写法、不同插件。

所以 src/config/mcp-config-normalize.ts 负责把它们整理成 runtime 可以使用的形态。

如果 MCP server 配了但没有工具出现，不要只查 server。也要查配置是否被正确归一化。

MCP 和 Plugin 怎么选

适合 MCP：

外部服务已经有 MCP server
希望跨 Agent/跨工具复用
能力边界清晰

适合 Plugin：

深度绑定 OpenClaw
要提供 channel/provider/resource package
需要 OpenClaw plugin-sdk 能力

排障顺序

1. MCP 配置是否被加载
2. server 是否能启动/连接
3. tools 是否被发现
4. tools 是否 materialize 到 bundle
5. tool policy 是否允许
6. provider 是否支持对应 tool call
7. 执行错误是否被隐藏或 redacted

实践：MCP 链路定位

用 3—5 分钟在源码中依次找到 src/config/mcp-config-normalize.ts、src/agents/agent-bundle-mcp-materialize.ts、src/agents/agent-bundle-mcp-tools.ts 和 src/mcp/。把它们分别标到“配置归一化、工具物化、工具进入 bundle、连接外部能力”这条链路上。

完成标准

• 四个源码入口均已核对；
• 能解释 server 已连接但工具仍不可见时为何要检查 policy；
• 能区分 MCP 与 Plugin 的适用边界。

多走一步

若当前已有 MCP 配置，只读确认它是否被加载以及工具是否被发现；不要为了练习添加未知 server。

下一篇看什么

下一篇看安全边界。