MCP集成详解：连接外部世界

MCP集成详解：连接外部世界

MCP（模型上下文协议）是 OpenClaw 对接外部数据源和第三方服务的标准通道。本节从协议原理讲起，手把手带你搭一个 MCP 服务器，再对比 Skill 和 MCP 的适用场景，帮你做出正确的技术选型。

本节导航

• 理解 MCP 协议的三大原语（工具、资源、提示模板）及其通信机制
• 掌握 MCP 服务器的开发流程：初始化项目、注册工具、配置连接
• 能独立完成一个天气查询 MCP 服务器的搭建与 OpenClaw 对接
• 清楚 Skill 和 MCP 的边界，在实际项目中做出合理选择

一、MCP 协议是什么

1.1 一句话理解

MCP 就是 AI 的 USB-C 接口。就像 USB-C 让手机能连接各种外设一样，MCP 让 AI 智能体能连接各种外部系统——数据库、API、文件系统、第三方服务。

在 MCP 出现之前，每个 AI 应用要对接一个新服务，都得写一套定制代码。有了 MCP，只要服务实现了 MCP 协议，任何支持 MCP 的 AI 应用都能直接调用，不需要重复开发。

1.2 协议架构

MCP 采用客户端-服务器架构，基于 JSON-RPC 2.0 协议通信：

OpenClaw 在这个架构里扮演 Host 角色，内部维护多个 MCP Client，每个 Client 连接一个 MCP Server。Server 是独立的进程，可以跑在本地（STDIO 传输），也可以跑在远程机器上（HTTP 传输）。

1.3 三大原语

MCP 服务器通过三种原语向 AI 暴露能力：

工具是最常用的原语。一个工具调用走的是标准的 JSON-RPC 请求-响应流程：客户端发送工具名称和参数，服务器执行后返回结果。

💡 选择建议：如果你的场景只需要让 AI 读取信息，用 Resources 就够了；如果需要 AI 执行操作（创建、修改、删除），那就得用 Tools。Prompts 用得相对少，主要在需要标准化交互流程时才会用到。

二、动手搭建 MCP 服务器

2.1 环境准备

搭建一个 MCP 服务器需要 Node.js 22+ 和 npm。先初始化项目：

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
​

在 package.json 里加上 "type": "module" 启用 ES 模块。

2.2 编写服务器代码

创建一个 index.js 文件，实现一个天气查询服务器：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "weather-mcp-server",
  version: "1.0.0"
});

// 注册工具
server.addTool({
  name: "get_weather",
  description: "查询指定城市的当前天气信息",
  inputSchema: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "城市名称，如 Beijing、Shanghai"
      },
      units: {
        type: "string",
        enum: ["metric", "imperial"],
        description: "温度单位：metric=摄氏度, imperial=华氏度"
      }
    },
    required: ["city"]
  }
});

// 处理工具调用
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_weather") {
    // 这里调用实际的天气 API
    const weather = await fetchWeather(args.city, args.units);
    return {
      content: [{
        type: "text",
        text: `${args.city} 当前天气：${weather.temperature}°，${weather.description}`
      }]
    };
  }
});

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

这段代码做了三件事：定义工具的名称和参数结构、注册工具调用的处理逻辑、通过 STDIO 传输启动服务。

2.3 配置 OpenClaw 连接

服务器写好后，告诉 OpenClaw 去哪里找它。编辑 OpenClaw 配置文件：

{
  skills: {
    load: {
      extraDirs: ["./my-mcp-server"]
    }
  }
}
​

OpenClaw 启动时会自动发现并启动这个 MCP 服务器。AI 智能体在对话中就能调用 get_weather 工具了。

⚠️ 端口冲突注意：STDIO 模式的 MCP 服务器不需要端口，它通过标准输入输出和 OpenClaw 通信。如果你改用 HTTP 传输模式，需要确保端口没有被其他服务占用。可以在启动脚本里加一个端口检测逻辑，发现冲突时自动切换到备用端口。

2.4 调试技巧

开发 MCP 服务器时，最容易遇到的问题就是"工具没被识别"。排查步骤：

1. 先单独运行服务器，确认它能正常启动
2. 检查 OpenClaw 日志里有没有 MCP 连接相关的错误信息
3. 确认工具的 inputSchema 格式正确，JSON Schema 语法没问题
4. 用 OpenClaw 的调试模式查看工具是否出现在可用工具列表里

三、Skill 与 MCP 的选型对比

在实际项目中，有些功能用 Skill 实现更合适，有些用 MCP 更好。两者的核心区别在于：Skill 传递的是静态知识，MCP 连接的是动态数据。

3.1 核心维度对比

3.2 决策流程

遇到一个需求时，按这个流程判断用 Skill 还是 MCP：

举几个实际例子：

• PDF 文本提取：操作是确定性的，用 pdfplumber 脚本就能搞定，适合 Skill
• GitHub PR 管理：需要访问远程 API，数据实时变化，需要 Token 认证，适合 MCP
• 企业代码规范：静态知识，需要详细指导和示例，适合 Skill
• 数据库查询：动态数据，数据量大，需要认证，适合 MCP

3.3 混合使用才是正解

实际项目里，Skill 和 MCP 往往搭配使用。以 DevOps 助手为例：

配置里同时启用 Skill 和 MCP：

{
  skills: {
    entries: {
      "cicd-workflow": { enabled: true },
      "log-analysis": { enabled: true },
      "deployment-guide": { enabled: true }
    },
    load: {
      extraDirs: [
        "./mcp-servers/jenkins",
        "./mcp-servers/k8s"
      ]
    }
  }
}
​

💡 经验之谈：不要纠结于"到底用 Skill 还是 MCP"这个问题。如果一个功能用 Skill 能搞定（比如只是封装一个命令行工具），那就先用 Skill，别过度设计。等到需求变复杂了（需要认证、需要实时数据），再迁移到 MCP 也不迟。

四、进阶技巧与安全实践

4.1 资源缓存

频繁访问的数据加一层缓存，减少 API 调用次数：

const cache = new Map();

server.addResource({
  uri: "cache://project-status",
  name: "项目状态缓存",
  async handler() {
    if (!cache.has("status")) {
      cache.set("status", await fetchProjectStatus());
      // 5 分钟后过期
      setTimeout(() => cache.delete("status"), 300000);
    }
    return cache.get("status");
  }
});
​

4.2 安全要点

MCP 服务器直接操作外部系统，安全不能马虎：

• 认证信息用环境变量注入，不要硬编码在代码里
• 对用户输入的参数做校验，防止注入攻击
• 远程服务器必须用 HTTPS 传输
• 遵循最小权限原则，服务器只暴露必要的工具
• 日志中不要输出敏感信息（API Key、密码等）

⚠️ 常见错误：很多初学者在开发时把 API Key 直接写在代码里，调试完忘了删，提交到代码仓库。建议从一开始就用环境变量，养成习惯。

图：MCP集成架构

本节要点

1. MCP 是 AI 智能体连接外部世界的标准协议，基于 JSON-RPC 2.0 通信
2. 三大原语各司其职：Tools 执行操作、Resources 提供数据、Prompts 定义模板
3. 开发 MCP 服务器的核心步骤：初始化项目 → 注册工具 → 配置 OpenClaw 连接
4. Skill 适合静态知识和工作流程，MCP 适合动态数据和外部服务，两者搭配使用效果最好
5. 安全不是事后补丁，从第一天就要用环境变量管理密钥，做好输入校验