第10章 MCP 集成：连接外部工具生态

一个开放协议如何让 Agent 接入全世界的工具

10.1 本章导读

第9章的插件是"私有扩展"——你写代码、打包、安装。本章讲一种更开放的方式：MCP（Model Context Protocol），一个工具接入的标准协议。只要某个工具方提供了 MCP Server（文件系统、数据库、GitHub、Slack……社区已有成百上千个），你不用写一行适配代码就能接入。

10.2 MCP 是什么：工具的 USB 接口

对比第9章的插件体系：

10.3 本项目的 MCP 架构：三种传输

MCP 支持多种传输。本项目当前支持 stdio、SSE 和 streamable-http：stdio 把 Server 作为子进程拉起并通过 stdin/stdout 做 JSON-RPC 2.0 通信；远程 Server 则通过 URL、请求头和 HTTP/SSE 语义接入。

关键类分工：

10.3.1 握手序列

StdioMcpClient.connect() 内部是标准 MCP 初始化握手：

// StdioMcpClient.connect()（简化）
ProcessBuilder pb = new ProcessBuilder(cmd);   // 拉起 MCP Server 子进程
// ...
sendAndWait("initialize", Map.of(...));         // 1. 发送 initialize 请求
sendNotification("notifications/initialized", Map.of());  // 2. 发送 initialized 通知
// 此后即可 listTools / callTool

10.4 动手：接入一个文件系统 MCP Server

以社区官方的 filesystem Server 为例，在 harness.yml 配置：

harness:
  extensions:
    mcp:
      enabled: true
      servers:
        - name: filesystem
          transport: stdio
          command: npx
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
          env: {}
          cwd: ~

远程服务使用 transport: sse 或 transport: streamable-http，并声明 url；需要鉴权时配置 headers。无论哪种传输，注册后的工具都会进入同一个 ToolRegistry。

启动后，McpBootstrap 会拉起该 Server、列出它的工具（read_file、write_file、list_directory 等），注册为 mcp__filesystem__read_file 这样的工具名。之后 Agent 就能像调内置工具一样调它们——在控制台问"读一下 /tmp 下的某个文件"，模型会选择 mcp__filesystem__read_file。

10.5 当前边界

10.6 小结与下一章预告