🔗 MCP 协议完全实战指南

"世界上有一种协议叫 MCP，它像是 AI 和工具之间的翻译官。你说中文，它翻成代码；你想查数据，它递上结果。"

什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是连接 AI 模型与外部工具的标准协议。它定义了 AI 如何"发现"可用工具、如何"调用"这些工具、以及如何"理解"返回结果。

简单来说，MCP 就像是给 AI 装了一个 USB 接口——不管后面接的是硬盘、摄像头还是打印机，AI 都知道怎么和它对话。

为什么 MCP 很重要？

• 标准化 - 不同厂商的工具可以用统一方式接入
• 可发现 - AI 能自动了解有哪些工具可用
• 类型安全 - 参数和返回值都有明确定义
• 生态互通 - OpenClaw、Claude、GPT 都能用同一套工具

MCP 核心概念

1. Server（服务端）

提供工具能力的一方。可以是本地程序，也可以是远程服务。

2. Client（客户端）

使用工具的一方。在 OpenClaw 中，Agent 就是 MCP Client。

3. Tool（工具）

具体的功能单元，比如"搜索网页"、"读取文件"、"发送邮件"。

4. Resource（资源）

工具能访问的数据源，如数据库连接、API 密钥、文件路径等。

OpenClaw 中使用 MCP

配置 MCP Server

# mcp.config.json
{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    {
      "name": "brave-search",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  ]
}

在 Agent 中调用 MCP 工具

// 在 Agent 代码中使用 MCP
const { MCPClient } = require('openclaw/mcp');

class SearchAgent {
  async init() {
    this.mcp = new MCPClient();
    await this.mcp.connect('brave-search');
  }

  async search(query) {
    // AI 会自动选择合适的工具
    const tools = await this.mcp.listTools();
    console.log('可用工具:', tools.map(t => t.name));
    
    // 调用 brave_web_search 工具
    const result = await this.mcp.callTool('brave_web_search', {
      query: query,
      count: 10
    });
    
    return result.content;
  }
}

// 使用示例
const agent = new SearchAgent();
await agent.init();
const results = await agent.search('OpenClaw MCP 教程');

开发自定义 MCP Server

基础 Server 结构

// my-mcp-server.js
const { Server } = require('@modelcontextprotocol/sdk/server');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio');

const server = new Server(
  { name: 'my-custom-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

// 注册工具
server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      {
        name: 'calculate',
        description: '执行数学计算',
        inputSchema: {
          type: 'object',
          properties: {
            expression: {
              type: 'string',
              description: '数学表达式，如 "2 + 2"'
            }
          },
          required: ['expression']
        }
      }
    ]
  };
});

// 处理工具调用
server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'calculate') {
    const { expression } = request.params.arguments;
    try {
      // 注意：生产环境请使用安全的计算库
      const result = eval(expression);
      return {
        content: [{ type: 'text', text: String(result) }]
      };
    } catch (error) {
      return {
        content: [{ type: 'text', text: `计算错误: ${error.message}` }],
        isError: true
      };
    }
  }
  throw new Error(`未知工具: ${request.params.name}`);
});

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

最佳实践

安全注意事项

// ✅ 安全的参数校验
const sanitize = require('validator');

async handleCalculate(args) {
  const { expression } = args;
  
  // 只允许数学表达式
  if (!/^[\d+\-*/().\s]+$/.test(expression)) {
    throw new Error('表达式包含非法字符');
  }
  
  // 限制长度
  if (expression.length > 100) {
    throw new Error('表达式过长');
  }
  
  // 使用安全的计算方式
  return safeCalculate(expression);
}

MCP vs A2A：如何选择？

特性	MCP	A2A
定位	模型-工具协议	Agent-Agent协议
通信方式	同步调用	异步消息
适用场景	工具调用、数据获取	多Agent协作
复杂度	低	高

相关链接

• A2A 协议详解
• Agent Skills 开发指南
• 工作流编排教程
• MCP 术语百科
• MCP 官方文档