MCP 协议实战：让 Agent 连接一切工具

MCP 架构：

┌─────────────┐     MCP 协议     ┌─────────────┐
│  AI Agent   │ ←──────────────→ │  MCP Server │
│  (Client)   │    标准通信       │  (工具端)    │
└─────────────┘                  └─────────────┘
                                      │
                                      ├── 🔧 工具 (Tools)
                                      │    可被调用的函数
                                      │
                                      ├── 📄 资源 (Resources)
                                      │    可读取的数据
                                      │
                                      └── 💬 提示 (Prompts)
                                           可复用的提示模板

类比理解：
- MCP Client = 电脑（需要使用工具）
- MCP Server = USB 设备（提供工具能力）
- MCP 协议 = USB 标准（统一的通信规则）

为什么需要 MCP？
- Function Calling：每个 Agent 自己定义工具 → 不通用
- MCP：统一的工具协议 → 写一次，所有 Agent 都能用

在 Cursor 中创建一个简单的 MCP Server：

// 示例：天气查询 MCP Server

const { Server } = require("@modelcontextprotocol/sdk/server");
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio");

const server = new Server({
  name: "weather-server",
  version: "1.0.0",
}, {
  capabilities: {
    tools: {},  // 声明支持工具能力
  },
});

// 注册工具
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_weather",
      description: "获取指定城市的天气预报",
      inputSchema: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "城市名称，如'北京'"
          }
        },
        required: ["city"]
      }
    }
  ]
}));

// 处理工具调用
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const city = request.params.arguments.city;
    // 调用真实天气 API
    const weather = await fetchWeatherData(city);
    return {
      content: [{ type: "text", text: JSON.stringify(weather) }]
    };
  }
});

// 启动服务
const transport = new StdioServerTransport();
await server.connect(transport);

好的工具设计原则：

1. 单一职责
   ✅ get_weather(city) — 只查天气
   ❌ get_all_info(city) — 又查天气又查新闻

2. 参数明确
   ✅ city: string, days: integer(1-7)
   ❌ query: string（太模糊）

3. 返回结构化
   ✅ { temp: 22, condition: "晴", wind: "东南3级" }
   ❌ "北京今天22度晴东南风3级"（非结构化）

4. 错误清晰
   ✅ { error: "城市不存在", code: "CITY_NOT_FOUND" }
   ❌ { error: "失败" }

常用 MCP Server 清单：

📦 文件系统
   - 读写本地文件
   - 搜索文件和目录

📦 数据库
   - 查询 SQL / NoSQL 数据库
   - 支持 MySQL、PostgreSQL、MongoDB

📦 浏览器
   - Puppeteer / Playwright 驱动
   - 网页截图、表单填写、数据提取

📦 GitHub
   - 管理 Issue / PR
   - 搜索代码和仓库

📦 Slack / 飞书
   - 发送和读取消息
   - 管理频道和用户

OpenClaw MCP 配置：

mcp_servers:
  - name: weather
    command: node
    args: ["./mcp-servers/weather/index.js"]
    
  - name: database
    command: python
    args: ["./mcp-servers/database/server.py"]
    env:
      DB_URL: "postgresql://..."
      
  - name: browser
    command: npx
    args: ["@playwright/mcp@latest"]

Cursor MCP 配置（.cursor/mcp.json）：
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["./mcp-servers/weather/index.js"]
    },
    "database": {
      "command": "python",
      "args": ["./mcp-servers/database/server.py"],
      "env": {
        "DB_URL": "postgresql://..."
      }
    }
  }
}

配置后，Agent 自动获得所有 MCP 工具：
- 天气查询、数据库操作、浏览器自动化
- 无需写 Function Calling 定义
- MCP Server 更新后，Agent 自动获得新能力

多工具协同示例：

用户："查一下北京明天天气，如果下雨就发 Slack 通知团队明天居家办公"

Agent 自动编排：
1. 调用 weather Server → get_weather("北京", 1)
   → 结果：明天中雨 🌧️
   
2. 判断：需要发通知
   
3. 调用 Slack Server → send_message(
     channel: "#team-notice",
     message: "🌧️ 明天北京中雨，建议居家办公"
   )
   → 通知发送成功

Agent 不需要预先知道这个流程，
MCP 让它能"看到"所有可用工具，
自主规划调用顺序。

安全边界：
- 每个 MCP Server 可以设置权限范围
- weather Server：只读，无风险
- database Server：只允许 SELECT，禁止写操作
- Slack Server：只能发到特定频道
- 浏览器 Server：限制访问域名白名单

MCP 资源（Resources）用法：

资源是 MCP 中的只读数据，Agent 可以按需获取：

1. 文档资源
   URI: "docs://api-reference"
   → Agent 可以读取 API 文档来了解如何调用

2. 数据资源
   URI: "data://sales-2026-q1"
   → Agent 可以读取季度销售数据进行分析

3. 配置资源
   URI: "config://brand-voice"
   → Agent 可以读取品牌风格指南

vs. 工具（Tools）：
- 工具：Agent 主动调用，执行操作
- 资源：Agent 按需读取，获取信息

MCP 提示（Prompts）用法：

预定义的提示模板，Agent 可以复用：
- "summarize-document" → 文档摘要模板
- "code-review" → 代码审查模板
- "translate" → 翻译模板

Agent 使用时可以传入变量：
prompt: "summarize-document"
arguments: { doc_uri: "docs://quarterly-report" }

企业内部 MCP Server 示例：

1. ERP 系统 Server
   工具：
   - query_inventory(sku) → 查库存
   - create_order(items, customer) → 创建订单
   - get_delivery_status(order_id) → 查物流

2. OA 系统 Server
   工具：
   - submit_leave(type, dates) → 提交请假
   - approve_request(request_id) → 审批
   资源：
   - "oa://org-chart" → 组织架构
   - "oa://policies" → 公司政策

3. 监控系统 Server
   工具：
   - get_alerts(severity) → 获取告警
   - ack_alert(alert_id) → 确认告警
   资源：
   - "monitor://dashboard" → 仪表盘数据

部署架构：
企业内网 → MCP Server → Agent
           ↑
    只在内网暴露
    Agent 通过安全网关访问
    所有调用走审计日志

MCP 最佳实践清单：

1. 工具粒度
   - 太粗：一个工具做太多事 → 难以复用
   - 太细：一个工具只做一步 → 调用链太长
   - 合适：一个工具完成一个用户意图

2. 安全策略
   - 所有 MCP Server 必须有权限控制
   - 写操作需要人工确认
   - 敏感数据脱敏返回
   - 调用频率限制

3. 错误处理
   - Server 崩溃 → Agent 降级到无工具模式
   - 工具调用超时 → 30秒超时 + 重试1次
   - 参数校验失败 → 明确错误信息

4. 可观测性
   - 记录每次工具调用
   - 监控 Server 健康状态
   - 统计工具使用频率（优化常用工具）

5. 版本管理
   - 工具接口变更需要版本号
   - 向后兼容：新增参数有默认值
   - 废弃工具标记 deprecated，给迁移期