数据层协议

2.1 JSON-RPC 2.0基础

MCP的数据层基于 JSON-RPC 2.0 规范。所有消息都是JSON格式，分三类：

请求 (Request)

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

jsonrpc: 固定为 "2.0"
id: 请求唯一标识（字符串或数字），用于匹配响应
method: 调用的方法名
params: 方法参数（可选，Object类型）

响应 (Response)

成功响应：

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

错误响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32601, "message": "Method not found", "data": {} }
}

result 和 error 互斥，一个响应只会包含其中之一。

通知 (Notification)

没有 id 字段，不期望响应：

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

通知是单向的，发送方不需要等待任何回复。

2.2 Server端 Primitive

MCP Server可以暴露三种核心能力：

Tools（工具）— 模型控制

可执行的函数。AI模型自主决定何时调用。

方法	方向	用途
`tools/list`	Client → Server	列出所有可用工具（支持分页）
`tools/call`	Client → Server	执行指定工具
`notifications/tools/list_changed`	Server → Client	工具列表变更通知

工具定义（协议版本 2025-11-25）:

{
  "name": "check_inventory",
  "title": "库存查询",
  "description": "查询指定SKU的实时库存数量",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "description": "商品SKU编号" },
      "warehouse": { "type": "string", "description": "仓库代码（可选）" }
    },
    "required": ["sku"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "sku": { "type": "string" },
      "quantity": { "type": "number" },
      "warehouses": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "code": { "type": "string" },
            "quantity": { "type": "number" }
          }
        }
      }
    }
  }
}

关键字段说明:

name: 工具的唯一标识符
title: 人类可读的显示名称
description: 描述工具用途，直接影响AI模型的选择决策
inputSchema: JSON Schema格式的输入参数定义（必需）
outputSchema: JSON Schema格式的输出结构定义（可选，2025-11-25 新增）

工具执行结果:

{
  "content": [
    { "type": "text", "text": "SKU SHOE-001 库存: 北京仓 45件, 上海仓 23件" }
  ],
  "structuredContent": {
    "sku": "SHOE-001",
    "quantity": 68,
    "warehouses": [
      { "code": "BJ", "quantity": 45 },
      { "code": "SH", "quantity": 23 }
    ]
  },
  "isError": false
}

content: 内容数组，支持多种类型（text、image、audio、resource_link、embedded_resource）
structuredContent: 与 outputSchema 对应的结构化数据（可选，与 content 同时返回，优先用于程序化处理）
isError: 标识是否为工具级错误（true 表示工具执行失败但协议层正常）

两种错误类型:

协议层错误: JSON-RPC error响应，表示请求本身有问题（方法不存在、参数无效等）
工具层错误: isError: true，表示工具执行了但遇到业务错误（商品不存在、权限不足等）

Resources（资源）— 应用控制

数据源，提供上下文信息。和Tools的区别：Tools是”做事”，Resources是”提供信息”。

方法	方向	用途
`resources/list`	Client → Server	列出所有可用资源（支持分页）
`resources/read`	Client → Server	读取指定资源
`resources/subscribe`	Client → Server	订阅资源变化
`resources/unsubscribe`	Client → Server	取消订阅
`notifications/resources/list_changed`	Server → Client	资源列表变更通知
`notifications/resources/updated`	Server → Client	已订阅资源内容变更通知

资源定义:

{
  "uri": "commerce://catalog/categories",
  "name": "商品分类",
  "description": "当前所有商品分类及其层级结构",
  "mimeType": "application/json",
  "annotations": {
    "audience": ["user", "assistant"],
    "priority": 0.8,
    "lastModified": "2026-04-10T08:00:00Z"
  }
}

Annotations字段说明:

audience: 目标受众，可选值包括 "user" 和 "assistant"
priority: 优先级，0到1之间的浮点数（1为最高优先级）
lastModified: 最后修改时间（ISO 8601格式）

URI模板: 资源URI支持RFC 6570 URI模板语法，用于定义动态资源：

commerce://products/{sku}
commerce://orders/{orderId}/items

Prompts（提示词模板）— 用户控制

可复用的交互模板。Server可以提供预定义的提示词，用户在Host应用中主动选择使用。

方法	方向	用途
`prompts/list`	Client → Server	列出所有可用提示词（支持分页）
`prompts/get`	Client → Server	获取指定提示词（支持arguments参数化）
`notifications/prompts/list_changed`	Server → Client	提示词列表变更通知

提示词定义:

{
  "name": "product_recommendation",
  "description": "根据用户需求推荐商品",
  "arguments": [
    { "name": "category", "description": "商品类别", "required": true },
    { "name": "budget", "description": "预算范围", "required": false }
  ]
}

获取提示词:

// Client → Server
{
  "method": "prompts/get",
  "params": {
    "name": "product_recommendation",
    "arguments": { "category": "运动鞋", "budget": "500-1000" }
  }
}

// Server → Client
{
  "result": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "请推荐500-1000元价位的运动鞋，考虑性价比、舒适度和品牌口碑。"
        }
      }
    ]
  }
}

2.3 Client端 Primitive

MCP Client也可以暴露能力给Server（需在初始化时声明）：

Sampling — Server请求LLM推理

Server无需内置AI SDK，可以请求Host的LLM完成推理。

// Server → Client
{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      { "role": "user", "content": { "type": "text", "text": "将以下文本翻译为英文：你好世界" } }
    ],
    "maxTokens": 100,
    "modelPreferences": {
      "hints": [{ "name": "claude-sonnet" }],
      "costPriority": 0.3,
      "speedPriority": 0.8,
      "intelligencePriority": 0.5
    }
  }
}

modelPreferences字段:

hints: 模型提示列表，Server建议使用的模型（Host可以忽略）
costPriority: 成本优先级（0-1，越高越倾向低成本模型）
speedPriority: 速度优先级（0-1，越高越倾向快速模型）
intelligencePriority: 智能优先级（0-1，越高越倾向高能力模型）

Elicitation — Server请求用户输入

Server需要用户确认或补充信息时使用。

// Server → Client
{
  "method": "elicitation/request",
  "params": {
    "message": "退货需要确认以下信息",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "reason": { "type": "string", "description": "退货原因" },
        "confirm": { "type": "boolean", "description": "确认退货" }
      },
      "required": ["reason", "confirm"]
    }
  }
}

Roots — 文件系统边界

Server查询可访问的文件系统范围。

// Server → Client
{ "method": "roots/list" }

// Client → Server
{
  "result": {
    "roots": [
      { "uri": "file:///home/user/project", "name": "项目目录" }
    ]
  }
}

Logging — 日志消息

Server向Client发送日志消息，用于调试和监控。

// Server → Client (通知)
{
  "method": "notifications/message",
  "params": {
    "level": "warning",
    "logger": "inventory-service",
    "data": "SKU SHOE-001 库存低于阈值"
  }
}

日志级别: debug、info、notice、warning、error、critical、alert、emergency。

2.4 能力协商

初始化时，双方声明支持的能力。只有声明的能力才能使用。 Server能力:

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

listChanged: Server会在列表变化时发送通知
subscribe: 支持资源订阅（内容变化时通知Client）

Client能力:

{
  "capabilities": {
    "sampling": {},
    "elicitation": {},
    "roots": { "listChanged": true }
  }
}

sampling: Client支持Server请求LLM推理
elicitation: Client支持Server请求用户输入
roots.listChanged: Client会在文件系统边界变化时通知Server

2.5 错误处理

MCP使用JSON-RPC 2.0标准错误码加上MCP自定义扩展：

标准JSON-RPC错误码

错误码	含义
-32700	JSON解析错误（Parse error）
-32600	无效的请求（Invalid Request）
-32601	方法不存在（Method not found）
-32602	无效的参数（Invalid params）
-32603	内部错误（Internal error）

MCP自定义错误码

错误码	含义	说明
-32001	请求超时	Server处理时间过长
-32002	资源不存在	请求的资源URI无效

工具层错误

工具执行中的业务错误不使用JSON-RPC error，而是通过正常响应中的 isError 标志传递：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      { "type": "text", "text": "订单 ORD-001 不存在或已取消" }
    ],
    "isError": true
  }
}

这种设计让AI模型能看到错误信息并据此调整行为（比如换一个订单号重试）。

下一章: 传输层 — stdio和Streamable HTTP两种传输方式详解

开始

学习路径

AI代理商务入门

OTR 开放信任协议

UCP 通用商务协议

ACP 代理商务协议

MCP 模型上下文协议

AI时代的SEO

ORBEXA 一体化方案

模板与提示词

术语词典

MCP数据层JSON-RPC协议详解

数据层协议

2.1 JSON-RPC 2.0基础

请求 (Request)

响应 (Response)

通知 (Notification)

2.2 Server端 Primitive

Tools（工具）— 模型控制

Resources（资源）— 应用控制

Prompts（提示词模板）— 用户控制

2.3 Client端 Primitive

Sampling — Server请求LLM推理

Elicitation — Server请求用户输入

Roots — 文件系统边界

Logging — 日志消息

2.4 能力协商

2.5 错误处理

标准JSON-RPC错误码

MCP自定义错误码

工具层错误

​数据层协议

​2.1 JSON-RPC 2.0基础

​请求 (Request)

​响应 (Response)

​通知 (Notification)

​2.2 Server端 Primitive

​Tools（工具）— 模型控制

​Resources（资源）— 应用控制

​Prompts（提示词模板）— 用户控制

​2.3 Client端 Primitive

​Sampling — Server请求LLM推理

​Elicitation — Server请求用户输入

​Roots — 文件系统边界

​Logging — 日志消息

​2.4 能力协商

​2.5 错误处理

​标准JSON-RPC错误码

​MCP自定义错误码

​工具层错误

数据层协议

2.1 JSON-RPC 2.0基础

请求 (Request)

响应 (Response)

通知 (Notification)

2.2 Server端 Primitive

Tools（工具）— 模型控制

Resources（资源）— 应用控制

Prompts（提示词模板）— 用户控制

2.3 Client端 Primitive

Sampling — Server请求LLM推理

Elicitation — Server请求用户输入

Roots — 文件系统边界

Logging — 日志消息

2.4 能力协商

2.5 错误处理

标准JSON-RPC错误码

MCP自定义错误码

工具层错误