AgentHarness 课程
Hermes 专题/课程概述

第三十七课：MCP 集成

MCP服务器配置工具发现自定义MCP服务器

学习目标

  • 理解 MCP（Model Context Protocol）协议的概念和架构
  • 掌握 MCP 服务器的配置方法
  • 了解工具发现机制
  • 学会创建自定义 MCP 服务器
  • 掌握常用 MCP 服务器的使用

一、MCP 协议概述

MCP（Model Context Protocol）是一个开放协议，让 AI 模型可以调用外部工具。它由 Anthropic 提出，现在被多个 AI 编码工具支持，包括 OpenAI Codex、Claude Code、Cursor 等。

1.1 为什么需要 MCP

AI 模型本身只能处理文本，无法直接访问文件系统、调用 API、操作数据库或控制外部设备。在没有 MCP 之前，每个 AI 工具都需要自己实现工具集成，导致：

  • 重复开发：每个工具都要实现相同的集成
  • 兼容性差：不同工具的工具接口不统一
  • 维护困难：工具更新需要同步更新所有集成

MCP 提供了一个标准化的方式，让模型可以调用外部能力，解决了这些问题。

1.2 MCP 架构

MCP 使用客户端-服务器架构：

客户端：AI 编码工具（如 Codex、Claude Code）

  • 负责与用户交互
  • 发送工具调用请求
  • 处理工具返回结果

服务器：提供工具能力的服务

  • 注册可用工具
  • 处理工具调用请求
  • 返回执行结果

通信协议：JSON-RPC 2.0

  • 请求-响应模式
  • 支持流式传输
  • 支持通知

1.3 工具类型

MCP 支持多种工具类型：

  • 文件系统工具：读写文件、目录管理
  • API 工具：调用外部 API
  • 数据库工具：查询和操作数据库
  • 搜索工具：网络搜索
  • 自定义工具：任意功能

二、配置方法

2.1 基本配置

在 ~/.codex/config.toml 中配置 MCP 服务器：

[mcp_servers.example]
command = "npx"
args = ["-y", "mcp-server-example"]

2.2 配置参数详解

  • command：启动服务器的命令，可以是 npx、node、python 等
  • args：命令参数，数组形式
  • env：环境变量，对象形式（可选）
  • cwd：工作目录（可选）

2.3 多个服务器配置

可以配置多个 MCP 服务器，每个服务器提供不同的工具能力：

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "your-token" }

[mcp_servers.database]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://..." }

2.4 配置验证

配置完成后，使用以下命令验证：

  • /mcp：查看已配置的 MCP 服务器
  • 查看服务器状态和可用工具

三、工具发现

3.1 自动发现

配置 MCP 服务器后，Codex 会自动发现服务器提供的工具。发现过程：

  1. 启动 MCP 服务器
  2. 发送工具列表请求
  3. 获取可用工具列表
  4. 注册到 Codex 的工具系统

3.2 工具列表

使用 /mcp 命令查看可用工具：

  • 服务器名称
  • 工具名称
  • 工具描述
  • 参数 Schema

3.3 工具调用

模型会自动选择合适的工具调用。调用过程：

  1. 模型分析用户需求
  2. 选择合适的工具
  3. 构造调用参数
  4. 发送到 MCP 服务器
  5. 接收返回结果
  6. 将结果加入上下文

四、自定义 MCP 服务器

4.1 使用 MCP SDK

使用 MCP SDK 创建自定义 MCP 服务器：

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

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

// 注册工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "my-tool",
      description: "My custom tool",
      inputSchema: {
        type: "object",
        properties: {
          input: { type: "string" }
        }
      }
    }]
  };
});

// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "my-tool") {
    const input = request.params.arguments.input;
    // 处理逻辑
    return { content: [{ type: "text", text: `Result: ${input}` }] };
  }
});

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

4.2 注册工具

在服务器中注册工具，定义：

  • 工具名称
  • 工具描述
  • 参数 Schema（JSON Schema 格式）

4.3 处理请求

实现工具的处理逻辑：

  • 解析输入参数
  • 执行业务逻辑
  • 返回结果

4.4 部署服务器

将服务器部署到可访问的位置：

  • npm 包：通过 npx 启动
  • 本地脚本：直接执行
  • 远程服务：通过 HTTP 连接

五、常用 MCP 服务器

5.1 文件系统服务器

@modelcontextprotocol/server-filesystem：

  • 提供文件系统访问能力
  • 支持读写文件、目录管理
  • 可配置访问权限

5.2 GitHub 服务器

@modelcontextprotocol/server-github：

  • 提供 GitHub API 访问能力
  • 支持仓库管理、Issue 处理
  • 需要 GitHub Token

5.3 数据库服务器

@modelcontextprotocol/server-postgres：

  • 提供 PostgreSQL 访问能力
  • 支持查询和操作
  • 需要数据库连接字符串

5.4 Web 搜索服务器

@modelcontextprotocol/server-brave-search：

  • 提供网络搜索能力
  • 支持多种搜索引擎
  • 需要 API Key

六、最佳实践

6.1 安全性

  • 限制工具权限
  • 验证输入参数
  • 使用环境变量存储敏感信息

6.2 性能

  • 缓存常用数据
  • 异步处理耗时操作
  • 限制并发请求数

6.3 可维护性

  • 清晰的工具描述
  • 完善的错误处理
  • 详细的日志记录

七、本课小结

要点说明
MCP 协议让 AI 调用外部工具的开放协议
架构客户端-服务器，JSON-RPC 2.0
配置config.toml 中配置服务器
工具发现自动发现服务器提供的工具
自定义使用 MCP SDK 创建服务器
常用服务器文件系统、GitHub、数据库、搜索

下一步

下一课我们将了解 Plugins 插件系统。