第14章 MCP集成 —— 扩展Harness的能力边界

上一篇我们剖析了上下文管理的四层策略。本章我们看 MCP集成——连接 AI 和外部系统的开放协议。

MCP 是什么

一句话定义:Model Context Protocol——连接 AI 和外部工具的开放协议,扩展 Harness 能力边界。

MCP = 连接外部系统的标准化协议 定位:Harness 的扩展层核心,连接任意外部系统

图表 代码
graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务] External -->|返回| MCP -->|结果| Agent
graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务] External -->|返回| MCP -->|结果| Agent
graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统
数据库/API/云服务] External -->|返回| MCP -->|结果| Agent
graph LR
    Agent[Agent Loop] -->|调用| MCP[MCP 服务器]
    MCP -->|连接| External[外部系统<br/>数据库/API/云服务]
    External -->|返回| MCP -->|结果| Agent

核心机制:

  • 标准协议:统一的工具定义和调用格式
  • 服务器模式:MCP 服务器提供工具集合
  • 动态注册:MCP 工具动态注册到 Harness
  • 扩展能力:连接任意外部系统

MCP 的设计理念

为什么需要 MCP

问题:内置工具数量有限,无法连接外部系统。

内置工具局限说明MCP 解决方案
数量有限Claude Code 内置 20+ 工具MCP 无限扩展
无法连接外部系统内置工具无法访问数据库、云服务MCP 连接任意外部系统
硬编码新工具需改源码MCP 动态注册
图表 代码
graph TB
    subgraph BuiltInTools["内置工具局限"]
        B1[数量有限
20+ 工具] B2[无法连接外部系统] B3[新工具需改源码] end subgraph MCPSolution["MCP 解决方案"] M1[无限扩展
任意 MCP 服务器] M2[连接任意外部系统] M3[动态注册
无需改源码] end BuiltInTools -->|解决| MCPSolution style BuiltInTools fill:#FFE0E0 style MCPSolution fill:#E0FFE0
graph TB
    subgraph BuiltInTools["内置工具局限"]
        B1[数量有限
20+ 工具] B2[无法连接外部系统] B3[新工具需改源码] end subgraph MCPSolution["MCP 解决方案"] M1[无限扩展
任意 MCP 服务器] M2[连接任意外部系统] M3[动态注册
无需改源码] end BuiltInTools -->|解决| MCPSolution style BuiltInTools fill:#FFE0E0 style MCPSolution fill:#E0FFE0
graph TB
    subgraph BuiltInTools["内置工具局限"]
        B1[数量有限
20+ 工具] B2[无法连接外部系统] B3[新工具需改源码] end subgraph MCPSolution["MCP 解决方案"] M1[无限扩展
任意 MCP 服务器] M2[连接任意外部系统] M3[动态注册
无需改源码] end BuiltInTools -->|解决| MCPSolution style BuiltInTools fill:#FFE0E0 style MCPSolution fill:#E0FFE0
graph TB
    subgraph BuiltInTools["内置工具局限"]
        B1[数量有限<br/>20+ 工具]
        B2[无法连接外部系统]
        B3[新工具需改源码]
    end
    
    subgraph MCPSolution["MCP 解决方案"]
        M1[无限扩展<br/>任意 MCP 服务器]
        M2[连接任意外部系统]
        M3[动态注册<br/>无需改源码]
    end
    
    BuiltInTools -->|解决| MCPSolution
    
    style BuiltInTools fill:#FFE0E0
    style MCPSolution fill:#E0FFE0

MCP 的核心优势

优势说明价值
标准化统一的工具定义格式易于集成
无限扩展可连接任意 MCP 服务器灵活扩展
动态注册新工具无需改源码维护简单
生态丰富开源 MCP 服务器众多快速接入

MCP 架构

客户端-服务器模式

图表 代码
graph TB
    subgraph MCPClient["MCP 客户端(Harness)"]
        C1[Agent Loop]
        C2[工具注册表]
        C3[MCP 客户端接口]
    end
    
    subgraph MCPServer["MCP 服务器"]
        S1[工具定义]
        S2[执行函数]
        S3[外部系统连接]
    end
    
    C3 -->|调用工具| S1
    S2 -->|执行| S3
    S3 -->|返回结果| S2 -->|返回| C3
    
    C2 -->|动态注册| C3
    C1 -->|调用| C2
graph TB
    subgraph MCPClient["MCP 客户端(Harness)"]
        C1[Agent Loop]
        C2[工具注册表]
        C3[MCP 客户端接口]
    end
    
    subgraph MCPServer["MCP 服务器"]
        S1[工具定义]
        S2[执行函数]
        S3[外部系统连接]
    end
    
    C3 -->|调用工具| S1
    S2 -->|执行| S3
    S3 -->|返回结果| S2 -->|返回| C3
    
    C2 -->|动态注册| C3
    C1 -->|调用| C2
graph TB
    subgraph MCPClient["MCP 客户端(Harness)"]
        C1[Agent Loop]
        C2[工具注册表]
        C3[MCP 客户端接口]
    end
    
    subgraph MCPServer["MCP 服务器"]
        S1[工具定义]
        S2[执行函数]
        S3[外部系统连接]
    end
    
    C3 -->|调用工具| S1
    S2 -->|执行| S3
    S3 -->|返回结果| S2 -->|返回| C3
    
    C2 -->|动态注册| C3
    C1 -->|调用| C2
graph TB
    subgraph MCPClient["MCP 客户端(Harness)"]
        C1[Agent Loop]
        C2[工具注册表]
        C3[MCP 客户端接口]
    end
    
    subgraph MCPServer["MCP 服务器"]
        S1[工具定义]
        S2[执行函数]
        S3[外部系统连接]
    end
    
    C3 -->|调用工具| S1
    S2 -->|执行| S3
    S3 -->|返回结果| S2 -->|返回| C3
    
    C2 -->|动态注册| C3
    C1 -->|调用| C2

MCP 通信协议

协议内容:

协议层内容说明
工具定义工具名称、参数schema、描述告诉 Model 有哪些工具可用
工具调用工具名称、参数值Model 决定调用工具
工具结果执行结果或错误信息返回给 Model

JSON 格式示例:

// 工具定义
{
  "name": "mcp_filesystem_read",
  "description": "Read file via MCP filesystem server",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path to read"
      }
    },
    "required": ["path"]
  }
}

// 工具调用
{
  "tool_name": "mcp_filesystem_read",
  "parameters": {
    "path": "/data/report.csv"
  }
}

// 工具结果
{
  "result": "file content...",
  "error": null
}

MCP 服务器类型

常见 MCP 服务器

MCP 服务器功能提供的工具适用场景
filesystem文件系统操作read_file、write_file、list_directory文件管理
database数据库连接query、insert、update、delete数据库操作
web网络访问fetch、search、browser_control网络交互
gitGit 操作status、diff、commit、pushGit 管理
slackSlack 集成send_message、read_channelSlack 通信
githubGitHub APIcreate_issue、create_pr、search_codeGitHub 操作
custom自定义系统企业 API、云服务定制需求
图表 代码
graph TB
    subgraph MCPServers["MCP 服务器生态"]
        S1[filesystem
文件系统] S2[database
数据库] S3[web
网络] S4[git
Git 操作] S5[slack
Slack 集成] S6[github
GitHub API] S7[custom
自定义] end Harness[Harness] -->|连接| MCPServers
graph TB
    subgraph MCPServers["MCP 服务器生态"]
        S1[filesystem
文件系统] S2[database
数据库] S3[web
网络] S4[git
Git 操作] S5[slack
Slack 集成] S6[github
GitHub API] S7[custom
自定义] end Harness[Harness] -->|连接| MCPServers
graph TB
    subgraph MCPServers["MCP 服务器生态"]
        S1[filesystem
文件系统] S2[database
数据库] S3[web
网络] S4[git
Git 操作] S5[slack
Slack 集成] S6[github
GitHub API] S7[custom
自定义] end Harness[Harness] -->|连接| MCPServers
graph TB
    subgraph MCPServers["MCP 服务器生态"]
        S1[filesystem<br/>文件系统]
        S2[database<br/>数据库]
        S3[web<br/>网络]
        S4[git<br/>Git 操作]
        S5[slack<br/>Slack 集成]
        S6[github<br/>GitHub API]
        S7[custom<br/>自定义]
    end
    
    Harness[Harness] -->|连接| MCPServers

filesystem MCP 示例

工具列表:

工具功能参数
read_file读取文件path
write_file写入文件path, content
list_directory列出目录path
create_directory创建目录path
delete_file删除文件path

使用示例:

# Model 调用 MCP filesystem
tool_use = {
    "name": "mcp_filesystem_read",
    "parameters": {
        "path": "/data/report.csv"
    }
}

# MCP 服务器执行
result = mcp_filesystem.read_file("/data/report.csv")

# 返回结果
messages.append({
    "role": "user",
    "content": f"File content:\n{result}"
})

database MCP 示例

工具列表:

工具功能参数
query执行 SQL 查询sql
insert插入数据table, data
update更新数据table, data, where
delete删除数据table, where

使用示例:

# Model 调用 MCP database
tool_use = {
    "name": "mcp_database_query",
    "parameters": {
        "sql": "SELECT * FROM users WHERE active = true"
    }
}

# MCP 服务器执行
result = mcp_database.query("SELECT * FROM users WHERE active = true")

# 返回结果
messages.append({
    "role": "user",
    "content": f"Query result:\n{result}"
})

MCP 动态注册

注册流程

图表 代码
sequenceDiagram
    participant Harness as Harness
    participant MCPClient as MCP 客户端
    participant MCPServer as MCP 服务器
    participant Registry as 工具注册表
    
    Harness->>MCPClient: 启动 MCP 客户端
    MCPClient->>MCPServer: 连接 MCP 服务器
    MCPServer-->>MCPClient: 返回工具列表
    
    MCPClient->>Registry: 动态注册工具
    Registry-->>Harness: 工具可用
    
    Harness->>Model: 注入工具 Schema
    Model->>Harness: tool_use (MCP 工具)
    
    Harness->>MCPClient: 调用 MCP 工具
    MCPClient->>MCPServer: 执行工具
    MCPServer-->>MCPClient: 返回结果
    MCPClient-->>Harness: 返回结果
sequenceDiagram
    participant Harness as Harness
    participant MCPClient as MCP 客户端
    participant MCPServer as MCP 服务器
    participant Registry as 工具注册表
    
    Harness->>MCPClient: 启动 MCP 客户端
    MCPClient->>MCPServer: 连接 MCP 服务器
    MCPServer-->>MCPClient: 返回工具列表
    
    MCPClient->>Registry: 动态注册工具
    Registry-->>Harness: 工具可用
    
    Harness->>Model: 注入工具 Schema
    Model->>Harness: tool_use (MCP 工具)
    
    Harness->>MCPClient: 调用 MCP 工具
    MCPClient->>MCPServer: 执行工具
    MCPServer-->>MCPClient: 返回结果
    MCPClient-->>Harness: 返回结果
sequenceDiagram
    participant Harness as Harness
    participant MCPClient as MCP 客户端
    participant MCPServer as MCP 服务器
    participant Registry as 工具注册表
    
    Harness->>MCPClient: 启动 MCP 客户端
    MCPClient->>MCPServer: 连接 MCP 服务器
    MCPServer-->>MCPClient: 返回工具列表
    
    MCPClient->>Registry: 动态注册工具
    Registry-->>Harness: 工具可用
    
    Harness->>Model: 注入工具 Schema
    Model->>Harness: tool_use (MCP 工具)
    
    Harness->>MCPClient: 调用 MCP 工具
    MCPClient->>MCPServer: 执行工具
    MCPServer-->>MCPClient: 返回结果
    MCPClient-->>Harness: 返回结果
sequenceDiagram
    participant Harness as Harness
    participant MCPClient as MCP 客户端
    participant MCPServer as MCP 服务器
    participant Registry as 工具注册表
    
    Harness->>MCPClient: 启动 MCP 客户端
    MCPClient->>MCPServer: 连接 MCP 服务器
    MCPServer-->>MCPClient: 返回工具列表
    
    MCPClient->>Registry: 动态注册工具
    Registry-->>Harness: 工具可用
    
    Harness->>Model: 注入工具 Schema
    Model->>Harness: tool_use (MCP 工具)
    
    Harness->>MCPClient: 调用 MCP 工具
    MCPClient->>MCPServer: 执行工具
    MCPServer-->>MCPClient: 返回结果
    MCPClient-->>Harness: 返回结果

注册实现

# MCP 动态注册实现
def register_mcp_server(mcp_server_name, mcp_server_config):
    # 连接 MCP 服务器
    mcp_client = MCPClient(mcp_server_config)
    
    # 获取工具列表
    tools = mcp_client.list_tools()
    
    # 动态注册到 dispatch_map
    for tool in tools:
        # 工具名称:MCP_{server_name}_{tool_name}
        tool_name = f"mcp_{mcp_server_name}_{tool['name']}"
        
        # 注册 handler
        dispatch_map[tool_name] = lambda args: mcp_client.call_tool(tool['name'], args)
        
        # 注册 Schema
        tools_schema.append({
            "name": tool_name,
            "description": tool['description'],
            "parameters": tool['parameters']
        })

# 示例:注册 filesystem MCP
register_mcp_server("filesystem", {
    "url": "stdio://./mcp-servers/filesystem"
})

# dispatch_map 新增:
# "mcp_filesystem_read_file": mcp_filesystem_read_file_handler
# "mcp_filesystem_write_file": mcp_filesystem_write_file_handler
# "mcp_filesystem_list_directory": mcp_filesystem_list_directory_handler

多 MCP 服务器注册

# 注册多个 MCP 服务器
mcp_servers = {
    "filesystem": {"url": "stdio://./mcp-servers/filesystem"},
    "database": {"url": "stdio://./mcp-servers/database"},
    "web": {"url": "stdio://./mcp-servers/web"},
    "github": {"url": "stdio://./mcp-servers/github"}
}

for server_name, config in mcp_servers.items():
    register_mcp_server(server_name, config)

# dispatch_map 新增:
# filesystem: mcp_filesystem_* (5 tools)
# database: mcp_database_* (4 tools)
# web: mcp_web_* (3 tools)
# github: mcp_github_* (10 tools)

MCP 配置

配置文件

settings.json 配置:

{
  "mcpServers": {
    "filesystem": {
      "command": "./mcp-servers/filesystem",
      "args": [],
      "env": {}
    },
    "database": {
      "command": "./mcp-servers/database",
      "args": ["--db", "postgresql://localhost/mydb"],
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    },
    "github": {
      "command": "./mcp-servers/github",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

MCP 服务器启动

启动方式:

启动方式说明示例
stdio标准输入输出通信stdio://./mcp-server
HTTPHTTP 服务器http://localhost:3000
WebSocketWebSocket 通信ws://localhost:3000
图表 代码
graph LR
    Harness[Harness] -->|连接| Stdio[stdio
标准输入输出] Harness -->|连接| HTTP[HTTP
HTTP 服务器] Harness -->|连接| WebSocket[WebSocket
WebSocket 服务器] Stdio -->|通信| MCP[MCP 服务器] HTTP -->|通信| MCP WebSocket -->|通信| MCP
graph LR
    Harness[Harness] -->|连接| Stdio[stdio
标准输入输出] Harness -->|连接| HTTP[HTTP
HTTP 服务器] Harness -->|连接| WebSocket[WebSocket
WebSocket 服务器] Stdio -->|通信| MCP[MCP 服务器] HTTP -->|通信| MCP WebSocket -->|通信| MCP
graph LR
    Harness[Harness] -->|连接| Stdio[stdio
标准输入输出] Harness -->|连接| HTTP[HTTP
HTTP 服务器] Harness -->|连接| WebSocket[WebSocket
WebSocket 服务器] Stdio -->|通信| MCP[MCP 服务器] HTTP -->|通信| MCP WebSocket -->|通信| MCP
graph LR
    Harness[Harness] -->|连接| Stdio[stdio<br/>标准输入输出]
    Harness -->|连接| HTTP[HTTP<br/>HTTP 服务器]
    Harness -->|连接| WebSocket[WebSocket<br/>WebSocket 服务器]
    
    Stdio -->|通信| MCP[MCP 服务器]
    HTTP -->|通信| MCP
    WebSocket -->|通信| MCP

MCP vs 内置工具

对比

维度内置工具MCP 工具
数量固定(20+)无限(任意 MCP 服务器)
定义硬编码动态注册
外部系统❌ 无法连接✅ 连接任意系统
维护需改源码只需配置 MCP
生态Anthropic 提供开源生态丰富
定制❌ 无法定制✅ 自定义 MCP 服务器
图表 代码
graph TB
    subgraph BuiltIn["内置工具"]
        B1[数量固定
20+] B2[硬编码] B3[无法连接外部] end subgraph MCP["MCP 工具"] M1[数量无限
任意 MCP] M2[动态注册] M3[连接任意外部] end BuiltIn -->|扩展| MCP style BuiltIn fill:#FFE0E0 style MCP fill:#E0FFE0
graph TB
    subgraph BuiltIn["内置工具"]
        B1[数量固定
20+] B2[硬编码] B3[无法连接外部] end subgraph MCP["MCP 工具"] M1[数量无限
任意 MCP] M2[动态注册] M3[连接任意外部] end BuiltIn -->|扩展| MCP style BuiltIn fill:#FFE0E0 style MCP fill:#E0FFE0
graph TB
    subgraph BuiltIn["内置工具"]
        B1[数量固定
20+] B2[硬编码] B3[无法连接外部] end subgraph MCP["MCP 工具"] M1[数量无限
任意 MCP] M2[动态注册] M3[连接任意外部] end BuiltIn -->|扩展| MCP style BuiltIn fill:#FFE0E0 style MCP fill:#E0FFE0
graph TB
    subgraph BuiltIn["内置工具"]
        B1[数量固定<br/>20+]
        B2[硬编码]
        B3[无法连接外部]
    end
    
    subgraph MCP["MCP 工具"]
        M1[数量无限<br/>任意 MCP]
        M2[动态注册]
        M3[连接任意外部]
    end
    
    BuiltIn -->|扩展| MCP
    
    style BuiltIn fill:#FFE0E0
    style MCP fill:#E0FFE0

协作关系

内置工具 + MCP 工具:

图表 代码
graph LR
    subgraph Tools["工具系统"]
        BuiltIn[内置工具
Read/Write/Edit
Bash/Glob/Grep] MCP[MCP 工具
database/web
github/slack] end Agent[Agent Loop] -->|调用| Tools
graph LR
    subgraph Tools["工具系统"]
        BuiltIn[内置工具
Read/Write/Edit
Bash/Glob/Grep] MCP[MCP 工具
database/web
github/slack] end Agent[Agent Loop] -->|调用| Tools
graph LR
    subgraph Tools["工具系统"]
        BuiltIn[内置工具
Read/Write/Edit
Bash/Glob/Grep] MCP[MCP 工具
database/web
github/slack] end Agent[Agent Loop] -->|调用| Tools
graph LR
    subgraph Tools["工具系统"]
        BuiltIn[内置工具<br/>Read/Write/Edit<br/>Bash/Glob/Grep]
        MCP[MCP 工具<br/>database/web<br/>github/slack]
    end
    
    Agent[Agent Loop] -->|调用| Tools

分工:

  • 内置工具:核心操作(文件读写、命令执行、搜索导航)
  • MCP 工具:外部系统连接(数据库、云服务、企业 API)

MCP 的最佳实践

MCP 服务器选择

推荐 MCP 服务器:

场景推荐 MCP原因
文件管理filesystem基础文件操作
数据库操作databaseSQL 查询、数据管理
网络交互web网络请求、搜索
Git 管理gitGit 操作自动化
GitHub 集成githubPR、Issue 管理
Slack 通信slackSlack 消息发送

MCP 配置建议

配置优先级:

优先级MCP 类型说明
高filesystem基础文件操作
中database/web数据库和网络
低custom自定义系统

安全配置:

{
  "mcpServers": {
    "database": {
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD}"  // 使用环境变量
      },
      "permissions": {
        "deny": ["DELETE FROM *"]  // MCP 权限控制
      }
    }
  }
}

MCP 权限控制

MCP 权限继承 Harness 权限系统:

图表 代码
graph LR
    MCP[MCP 工具调用] -->|继承| Perm[Harness 权限系统]
    Perm -->|检查| Rules[权限规则]
    Rules -->|deny/ask/allow| Action[执行或拒绝]
graph LR
    MCP[MCP 工具调用] -->|继承| Perm[Harness 权限系统]
    Perm -->|检查| Rules[权限规则]
    Rules -->|deny/ask/allow| Action[执行或拒绝]
graph LR
    MCP[MCP 工具调用] -->|继承| Perm[Harness 权限系统]
    Perm -->|检查| Rules[权限规则]
    Rules -->|deny/ask/allow| Action[执行或拒绝]
graph LR
    MCP[MCP 工具调用] -->|继承| Perm[Harness 权限系统]
    Perm -->|检查| Rules[权限规则]
    Rules -->|deny/ask/allow| Action[执行或拒绝]

权限规则示例:

{
  "permissions": {
    "deny": [
      {"tool": "mcp_database_delete"}  // 禁止 MCP 删除操作
    ],
    "ask": [
      {"tool": "mcp_database_insert"},  // MCP 插入需审批
      {"tool": "mcp_database_update"}   // MCP 更新需审批
    ],
    "allow": [
      {"tool": "mcp_database_query"}  // MCP 查询自动执行
    ]
  }
}

MCP 的未来趋势

发展趋势

图表 代码
timeline
    title MCP 发展趋势
    2025 : MCP 协议发布
标准化工具连接 2025-06 : filesystem MCP
基础文件操作 2026 : database MCP
数据库集成 2026-03 : github MCP
GitHub 集成 2026-05 : 企业 MCP
企业 API 集成
timeline
    title MCP 发展趋势
    2025 : MCP 协议发布
标准化工具连接 2025-06 : filesystem MCP
基础文件操作 2026 : database MCP
数据库集成 2026-03 : github MCP
GitHub 集成 2026-05 : 企业 MCP
企业 API 集成
timeline
    title MCP 发展趋势
    2025 : MCP 协议发布
标准化工具连接 2025-06 : filesystem MCP
基础文件操作 2026 : database MCP
数据库集成 2026-03 : github MCP
GitHub 集成 2026-05 : 企业 MCP
企业 API 集成
timeline
    title MCP 发展趋势
    2025 : MCP 协议发布<br/>标准化工具连接
    2025-06 : filesystem MCP<br/>基础文件操作
    2026 : database MCP<br/>数据库集成
    2026-03 : github MCP<br/>GitHub 集成
    2026-05 : 企业 MCP<br/>企业 API 集成

生态丰富

趋势说明影响
开源 MCP 增多开源 MCP 服务器众多快速接入
企业 MCP 定制企业开发定制 MCP深度集成
MCP 标准化协议标准化推进易于集成

本章小结

  • MCP 定义:Model Context Protocol,连接 AI 和外部系统的开放协议
  • 核心优势:标准化、无限扩展、动态注册、生态丰富
  • 架构模式:客户端-服务器模式,MCP 服务器提供工具集合
  • 服务器类型:filesystem、database、web、git、slack、github、custom
  • 动态注册:连接 MCP → 获取工具列表 → 注册到 dispatch_map → 注入 Schema
  • 配置方式:settings.json 配置 MCP 服务器,stdio/HTTP/WebSocket 启动
  • 对比内置工具:内置固定有限,MCP 无限扩展动态注册
  • 协作关系:内置核心操作 + MCP 外部连接
  • 最佳实践:选择推荐 MCP、配置优先级、权限控制继承 Harness
  • 未来趋势:开源增多、企业定制、标准化推进

预告:下一篇我们深入技能系统——按需注入领域知识。



相关内容

如果这篇文章对你有帮助,欢迎请我喝杯咖啡 ☕
Cygnus Yang 支付宝支付宝
Cygnus Yang 微信微信