MCP消息与数据模型

3899 字约 13 分钟

AIAgentMCP协议

2026-07-24

MCP 的所有交互——工具调用、资源读取、Prompt 获取——最终都表现为结构化的消息交换。理解消息格式和数据模型，是开发 MCP Server/Client、调试协议交互、扩展协议能力的基础。

一、基本定义

MCP 消息与数据模型定义了协议中所有通信内容的格式、类型和结构规则。

核心组成：

消息格式：基于 JSON-RPC 2.0 的三种消息类型（请求、响应、通知）
内容类型（Content）：文本、图片、嵌入资源等多模态数据载体
能力数据：Tool、Resource、Prompt 的定义结构和交互数据
辅助机制：分页、进度通知、取消、日志等协议级数据结构

二、为什么需要标准化数据模型

在没有统一数据模型的情况下：

每个集成方自定义消息格式，解析逻辑各不相同
多模态内容（文本、图片、音频）无法统一传递
错误处理和边界情况（分页、取消、超时）没有统一约定
新增能力（Tool/Resource/Prompt）无法被自动发现

标准化数据模型让 MCP 实现了：

一次实现、到处复用：任何 MCP Client 都能解析任何 MCP Server 的消息
多模态统一传递：不同内容类型有标准的表示方式
协议可演进：新增字段和方法不破坏旧版本兼容性

三、在 MCP 体系中的位置

消息层在传输层之上，数据模型层定义消息内容结构，协议机制层提供辅助能力。各层职责清晰，互不耦合。

参考 MCP架构总览了解整体架构分层，参考 MCP通信与传输了解底层传输方式。

四、消息基础：JSON-RPC 2.0

MCP 消息基于 JSON-RPC 2.0 规范。所有消息都是 JSON 对象，通过传输层发送。

JSON-RPC 2.0 提供三种消息类型：

消息类型	有 `id` 字段	是否需要响应	用途
Request（请求）	是	是	发起操作并获取结果
Response（响应）	是（与请求匹配）	—	回复请求的结果或错误
Notification（通知）	否	否	单向事件通知

[!tip] 判断技巧看消息里有没有 id 字段——有 id 的是请求或响应，没有 id 的是通知。

五、请求（Request）

请求用于发起一个操作并等待结果。

基本结构：

jsonrpc: 版本号，固定为 "2.0"
id: 请求唯一标识，用于匹配响应
method: 方法名，字符串
params: 参数对象（可选）

请求 ID 的作用：

将响应与对应的请求关联起来
支持异步场景：多个请求可以并发发出，通过 ID 匹配各自的响应
用于取消操作：通过 id 指定要取消的请求

方法命名规范：

MCP 使用点分隔的命名空间风格：

方法名	说明
`initialize`	初始化连接
`tools/list`	列出可用工具
`tools/call`	调用工具
`resources/list`	列出资源
`resources/read`	读取资源
`prompts/list`	列出 Prompt
`prompts/get`	获取 Prompt
`ping`	心跳检查

以 notifications/ 开头的方法名保留给通知使用。

六、响应（Response）

响应用于回复一个请求。每个请求必须有且仅有一个响应。

基本结构：

jsonrpc: "2.0"
id: 与请求的 id 匹配
二选一：
- result: 成功时的结果对象
- error: 失败时的错误对象

成功响应包含 result 字段，内容由具体方法定义。

错误响应包含 error 字段，通常包括：

code: 错误码（数字）
message: 错误描述（字符串）
data: 附加错误数据（可选）

MCP 还定义了协议级错误码，用于区分不同类型的错误（如方法不存在、参数无效等）。具体错误码以当前 MCP 规范版本为准。

七、通知（Notification）

通知是单向消息，不需要对方回复。

基本结构：

jsonrpc: "2.0"
method: 通知方法名
params: 参数对象（可选）
无 id 字段（这是与请求的关键区别）

常见通知类型：

通知方法	说明
`notifications/initialized`	客户端完成初始化
`notifications/cancelled`	取消请求
`notifications/progress`	进度更新
`notifications/resources/list_changed`	资源列表变更
`notifications/tools/list_changed`	工具列表变更
`notifications/prompts/list_changed`	Prompt 列表变更
`notifications/message`	日志消息

通知不保证送达——发送方不应依赖通知的到达来驱动关键逻辑。

八、内容类型（Content）

MCP 定义了统一的内容类型体系，用于在 Tool 结果、Resource 内容、Prompt 消息中传递多模态数据。

内容类型	说明	关键字段
TextContent	文本内容	`type: "text"`, `text`
ImageContent	图片内容	`type: "image"`, `data`（base64）, `mimeType`
AudioContent	音频内容	`type: "audio"`, `data`（base64）, `mimeType`
EmbeddedResource	嵌入资源引用	`type: "resource"`, `resource`

[!note] 关于 AudioContent AudioContent 是 MCP 规范后续版本中添加的类型。具体是否可用取决于你使用的 MCP 版本，请以当前规范为准。

EmbeddedResource 值得注意——它不是直接传递内容，而是引用一个 Resource，让接收方按需读取。这在内容较大或需要保持引用完整性时很有用。

具体字段以当前 MCP 规范版本为准。

九、Tool 相关数据

Tool 数据结构定义了工具的描述和交互方式。参考 MCP Tool能力了解完整能力说明。

Tool 定义结构：

name: 工具名称（字符串，唯一标识）
description: 工具描述（字符串，供 LLM 理解工具用途）
inputSchema: 输入参数的 JSON Schema 定义

Tool 调用通过 tools/call 请求发起，包含：

name: 要调用的工具名
arguments: 工具参数（符合 inputSchema 的对象）

Tool 调用结果包含：

content: 内容数组，由 Content 类型（TextContent、ImageContent 等）组成
isError: 布尔值，标识工具执行是否出错

[!important] Tool 结果 ≠ Tool 错误 isError: true 表示工具执行逻辑出错（如查询失败），不是协议级错误。协议级错误（如方法不存在）通过响应的 error 字段返回。

十、Resource 相关数据

Resource 数据结构定义了资源的元信息和访问方式。参考 MCP资源模型了解完整说明。

Resource 定义结构：

uri: 资源唯一标识符（URI 格式）
name: 资源名称（人类可读）
description: 资源描述（可选）
mimeType: 资源 MIME 类型（可选）

Resource 读取通过 resources/read 请求发起，传入 URI，返回 contents 数组，每个元素包含 URI 和对应的 Content 数据。

Resource URI 是结构化的，支持模板化 Resource 定义（Resource Template），允许动态匹配一类资源。

十一、Prompt 相关数据

Prompt 数据结构定义了提示模板的描述和交互方式。参考 MCP Prompt能力了解完整说明。

Prompt 定义结构：

name: Prompt 名称
description: Prompt 描述（可选）
arguments: 参数列表（可选），每个参数包含 name、description、required

Prompt 获取通过 prompts/get 请求发起，传入 Prompt 名称和参数值，返回 messages 数组。

PromptMessage 结构：

role: 消息角色（user 或 assistant）
content: 内容对象（使用上述 Content 类型）

一个 Prompt 可以返回多条 PromptMessage，构成一段完整的对话上下文。

十二、Schema：JSON Schema 参数定义

MCP 使用 JSON Schema 来定义 Tool 的输入参数（inputSchema）。

作用：

声明工具接受哪些参数、参数类型、是否必填
Client 可用 Schema 在调用前做本地校验
LLM 可依据 Schema 理解参数含义并生成正确参数

JSON Schema 在 MCP 中的典型使用：

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "搜索关键词"
    },
    "limit": {
      "type": "number",
      "description": "返回结果数量上限"
    }
  },
  "required": ["query"]
}

Schema 验证是 Client 的可选行为——Server 也应独立验证输入参数，不依赖 Client 端校验。

十三、元数据和 URI

URI 在 MCP 中的角色：

Resource 通过 URI 唯一标识
URI 支持自定义 scheme（如 file://、db://、自定义 scheme）
Resource Template 使用 URI 模板匹配一类资源

元数据贯穿整个数据模型：

Tool、Resource、Prompt 定义都包含描述性元数据
Content 包含 mimeType 等元信息
初始化响应中包含 Server 的能力元数据（支持哪些功能）

十四、分页（Pagination）

MCP 列表接口使用 cursor-based pagination（游标分页）。

工作方式：

Client 请求列表（如 tools/list）
Server 返回结果和 nextCursor（可选）
如果存在 nextCursor，Client 可携带该 cursor 再次请求获取下一页
直到 Server 不返回 nextCursor，表示已到最后一页

游标分页相比 offset 分页的优势：

数据变动时不会跳过或重复项
Server 端实现更灵活（不依赖固定偏移量）
适合动态列表（如实时变化的资源列表）

[!tip] 注意 cursor 是不透明的字符串——Client 不应解析或构造 cursor 值，只需原样传回。

十五、进度通知（Progress Notifications）

对于耗时较长的操作（如大文件处理、复杂查询），MCP 支持进度通知。

工作方式：

Client 在请求中携带 progressToken
Server 在处理过程中发送 notifications/progress 通知，附带 progressToken、当前进度 progress、总进度 total（可选）
Client 据此向用户展示进度或做其他处理

progressToken 的作用是将进度通知与原始请求关联起来。

十六、取消（Cancellation）

MCP 通过 notifications/cancelled 通知实现请求取消。

工作方式：

Client 发送请求（带有 id）
Client 决定取消该请求，发送 notifications/cancelled 通知，包含要取消的 requestId
Server 收到后应尽量终止对应操作

取消语义：

取消是"尽力而为"的——Server 可能已经完成操作，或无法中断
取消通知不保证在响应之前到达
如果 Server 已返回响应，取消通知应被忽略
Client 发送取消后仍应准备好接收响应

十七、日志消息（Logging）

MCP Server 可通过 notifications/message 通知向 Client 发送日志信息。

日志结构包含：

level: 日志级别
logger: 日志来源名称（可选）
data: 日志内容

日志级别通常包括：debug、info、warning、error 等。具体级别定义以当前 MCP 规范版本为准。

Client 可以根据配置决定如何处理日志——转发给用户、写入文件、或静默丢弃。

十八、数据模型结构概览

[!note] 图示说明此图为 MCP 核心数据模型的结构关系概览。具体字段和类型以当前 MCP 规范版本为准，此处不穷举所有字段。

十九、设计原则

MCP 数据模型遵循以下设计原则：

JSON-RPC 为基座：不重新发明消息协议，复用成熟的 JSON-RPC 2.0 规范
内容类型可组合：Content 类型是通用的构建块，Tool、Resource、Prompt 都可以使用
Schema 驱动：用 JSON Schema 定义参数，让验证和 LLM 理解都有据可依
渐进增强：分页、进度、取消等是可选机制，简单 Server 不需要实现所有特性
前向兼容：新增字段不破坏旧 Client，未知字段应被忽略而非报错
URI 统一标识：Resource 用 URI 标识，支持自定义 scheme，保持开放性

二十、常见误区

误区	事实
"通知需要回复"	通知没有 `id`，不需要也不应该回复
"Tool 返回 `isError: true` 就是协议错误"	`isError` 是工具逻辑错误，协议错误走 `error` 字段
"cursor 可以自定义构造"	cursor 是不透明字符串，只应原样传回
"取消是强制的"	取消是尽力而为的，Server 可以忽略
"所有 Content 类型所有版本都支持"	AudioContent 等是后续版本新增的，注意版本兼容
"inputSchema 是可选的"	Tool 必须有 `inputSchema`，否则 Client 无法校验参数
"Resource URI 可以是任意格式"	URI 应该有明确的 scheme 和结构，Resource Template 使用 RFC 6570 模板

二十一、实践检查清单

开发 MCP Server 时：

所有响应都包含正确的 id 匹配
错误响应使用标准错误码和错误消息
Tool 的 inputSchema 使用合法的 JSON Schema
列表接口支持分页（nextCursor）
长耗时操作支持进度通知
正确处理取消通知
Content 类型使用正确的 type 字段值

开发 MCP Client 时：

正确区分请求（有 id）和通知（无 id）
对未知字段做忽略处理（前向兼容）
不对 cursor 值做解析或假设
发送取消后仍处理可能的响应
验证 Tool 参数符合 inputSchema
处理所有 Content 类型（包括不认识的类型做降级）

二十二、与其他概念的关系

MCP基础：消息模型是 MCP 协议的核心组成部分
MCP架构总览：消息层在架构中的分层位置
MCP通信与传输：消息通过传输层传递，传输层决定编码和传输方式
MCP Tool能力：Tool 定义和调用是消息模型的重要应用场景
MCP资源模型：Resource 数据和读取交互遵循消息模型
MCP Prompt能力：Prompt 模板获取和消息返回遵循消息模型
MCP Server设计：Server 实现需要遵循消息模型规范
MCP Client设计：Client 实现需要正确解析和构造消息
MCP安全边界：消息中的权限控制和输入验证

二十三、适用边界

本文覆盖：

MCP 消息格式（JSON-RPC 2.0 三种消息类型）
内容类型体系（TextContent、ImageContent 等）
Tool/Resource/Prompt 的数据结构
分页、进度、取消、日志等协议机制
数据模型设计原则

本文不覆盖：

传输层细节（stdio、HTTP+SSE 的编码和连接管理）→ MCP通信与传输
具体 Tool/Resource/Prompt 的开发实现 → 各自专题文档
协议版本演化的完整历史 → 参考 MCP 官方规范
具体 SDK 的 API 用法 → 参考对应 SDK 文档

[!info] 版本提示 MCP 协议仍在活跃演进中。本文描述的是数据模型的通用结构和设计思路，具体字段名、类型、新增内容类型等可能随版本变化。始终以你使用的 MCP SDK 版本对应的官方规范为准。