MCP 基础协议

Model Context Protocol 的基础协议定义了客户端和服务器之间通信的核心机制。

协议概述

MCP 基于 JSON-RPC 2.0 标准，提供了一套完整的通信协议，包括：

• 生命周期管理: 连接建立、初始化和终止
• 传输层抽象: 支持多种传输方式
• 认证授权: 安全的身份验证和访问控制
• 错误处理: 标准化的错误响应机制

核心概念

JSON-RPC 2.0

MCP 严格遵循 JSON-RPC 2.0 规范：

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": { ... },
  "id": 1
}

消息类型

1. 请求 (Request)

客户端向服务器发送的操作请求：

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

2. 响应 (Response)

服务器对请求的回复：

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [...]
  },
  "id": 1
}

3. 通知 (Notification)

不需要响应的单向消息：

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///example.txt"
  }
}

4. 错误 (Error)

操作失败时的错误响应：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": 1
}

协议版本

版本声明

每个 MCP 实现必须声明支持的协议版本：

{
  "protocolVersion": "2025-06-18"
}

版本兼容性

• 向后兼容: 新版本支持旧版本的核心功能
• 功能检测: 通过能力声明检测支持的功能
• 优雅降级: 不支持的功能应优雅处理

能力系统

能力声明

客户端和服务器通过能力声明表明支持的功能：

{
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true },
    "prompts": { "listChanged": true },
    "experimental": {}
  }
}

标准能力

客户端能力

• roots: 文件系统根目录管理
• sampling: 内容采样支持
• experimental: 实验性功能

服务器能力

• tools: 工具提供和执行
• resources: 资源访问和订阅
• prompts: 提示模板生成
• experimental: 实验性功能

标准方法

核心方法

initialize

建立协议连接：

{
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { ... },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

ping

连接保活检测：

{
  "method": "ping"
}

工具方法

• tools/list: 列出可用工具
• tools/call: 执行工具调用

资源方法

• resources/list: 列出可用资源
• resources/read: 读取资源内容
• resources/subscribe: 订阅资源变更
• resources/unsubscribe: 取消资源订阅

提示方法

• prompts/list: 列出可用提示模板
• prompts/get: 获取提示模板内容

错误处理

标准错误代码

MCP 使用 JSON-RPC 2.0 标准错误代码，并扩展了特定错误：

代码	名称	描述
-32700	Parse error	JSON 解析错误
-32600	Invalid Request	无效请求
-32601	Method not found	方法不存在
-32602	Invalid params	无效参数
-32603	Internal error	内部错误
-32000	Server error	服务器错误

错误响应格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "type": "InvalidParamsError",
      "param": "name",
      "details": "Tool name is required"
    }
  },
  "id": 1
}

实现要求

必需功能

1. JSON-RPC 2.0 支持: 完整的协议实现
2. 初始化握手: 版本和能力协商
3. 错误处理: 标准化错误响应
4. 连接管理: 优雅的连接建立和终止

推荐功能

1. 连接保活: 定期 ping 检测
2. 重连机制: 自动重连和故障恢复
3. 日志记录: 详细的操作日志
4. 性能监控: 延迟和吞吐量指标

相关文档

• 生命周期管理 - 连接生命周期详解
• 传输层 - 支持的传输方式
• 认证授权 - 安全认证机制
• 安全最佳实践 - 安全实现指南