协议修订: 2025-06-18
模型上下文协议 (MCP) 为服务器向客户端提供资源提供了一种标准化的方式。资源允许服务器共享为语言模型提供上下文的数据，例如文件、数据库模式或特定于应用程序的信息。每个资源都由一个URI唯一标识。

​
用户交互模型

MCP 中的资源被设计为**应用程序驱动**，由宿主应用程序根据自身需求决定如何整合上下文。 例如，应用程序可以：
  • 通过 UI 元素（如树状或列表视图）暴露资源，供用户明确选择
  • 允许用户搜索和筛选可用资源
  • 根据启发式规则或 AI 模型的选择，实现上下文的自动包含
资源上下文选择器示例 然而，实现可以自由地通过任何适合其需求的界面模式来暴露资源——协议本身不强制要求任何特定的用户交互模型。

​
功能

支持资源的服务器**必须 (MUST)** 声明 resources 能力。 
{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}
该能力支持两个可选特性：
  • subscribe：客户端是否可以订阅以接收单个资源变化的通知。
  • listChanged：当可用资源列表发生变化时，服务器是否会发出通知。
subscribe 和 listChanged 都是可选的——服务器可以不支持、支持其中之一或两者都支持。 
{
  "capabilities": {
    "resources": {} // Neither feature supported
  }
}

{
  "capabilities": {
    "resources": {
      "subscribe": true // Only subscriptions supported
    }
  }
}

{
  "capabilities": {
    "resources": {
      "listChanged": true // Only list change notifications supported
    }
  }
}

​
协议消息

​
列出资源

为了发现可用资源，客户端发送一个 resources/list 请求。此操作支持分页。 **请求：**
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}
响应 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

​
读取资源

要检索资源内容，客户端发送一个 resources/read 请求： **请求：**
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}
响应 
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "mimeType": "text/x-rust",
        "text": "fn main() {\n    println!(\"Hello world!\");\n}"
      }
    ]
  }
}

​
资源模板

资源模板允许服务器使用 URI 模板暴露参数化资源。参数可以通过自动完成 API 进行自动补全。 **请求：**
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}
响应 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

​
列表变更通知

当可用资源列表发生变化时，声明了 listChanged 能力的服务器**应该 (SHOULD)** 发送一个通知。 
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
}

​
订阅

该协议支持对资源变化进行可选的订阅。客户端可以订阅特定资源，并在其发生变化时接收通知： **订阅请求：**
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}
更新通知 
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///project/src/main.rs",
    "title": "Rust Software Application Main File"
  }
}

​
消息流

​
数据类型

​
资源

一个资源定义包括：
  • uri：资源的唯一标识符
  • name：资源的名称。
  • title：可选的、供显示用的人类可读的资源名称。
  • description：可选的描述
  • mimeType：可选的 MIME 类型
  • size：可选的大小（以字节为单位）

​
资源内容

资源可以包含文本或二进制数据。

​
文本内容

{
  "uri": "file:///example.txt",
  "name": "example.txt",
  "title": "Example Text File",
  "mimeType": "text/plain",
  "text": "Resource content"
}

​
二进制内容

{
  "uri": "file:///example.png",
  "name": "example.png",
  "title": "Example Image",
  "mimeType": "image/png",
  "blob": "base64-encoded-data"
}

​
注解

资源、资源模板和内容块支持可选的注解，这些注解为客户端提供了关于如何使用或显示资源的提示。
  • audience：一个数组，指示此资源的目标受众。有效值为 "user" 和 "assistant"。例如，["user", "assistant"] 表示内容对两者都有用。
  • priority：一个从 0.0 到 1.0 的数字，表示此资源的重要性。值为 1 表示“最重要”（实际上是必需的），而 0 表示“最不重要”（完全可选）。
  • lastModified：一个 ISO 8601 格式的时间戳，指示资源最后一次被修改的时间（例如，"2025-01-12T15:00:58Z"）。
带注解的资源示例 
{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "title": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}
客户端可以使用这些注解来：
  • 根据目标受众筛选资源
  • 优先决定将哪些资源包含在上下文中
  • 显示修改时间或按新旧排序

​
通用 URI 方案

该协议定义了几种标准的 URI 方案。此列表并非详尽无遗——实现总是可以自由使用额外的、自定义的 URI 方案。

​
https://

用于表示网络上可用的资源。 服务器**应该 (SHOULD)** 仅在客户端能够自行从网络上直接获取和加载资源时使用此方案——也就是说，它不需要通过 MCP 服务器读取资源。 对于其他用例，即使服务器本身将通过互联网下载资源内容，服务器也**应该 (SHOULD)** 优先使用另一种 URI 方案，或定义一个自定义方案。

​
file://

用于标识行为类似文件系统的资源。然而，这些资源不一定需要映射到实际的物理文件系统。 MCP 服务器**可以 (MAY)** 使用 XDG MIME 类型（如 inode/directory）来标识 file:// 资源，以表示那些没有标准 MIME 类型的非常规文件（如目录）。

​
git://

Git 版本控制集成。

​
自定义 URI 方案

自定义 URI 方案**必须 (MUST)** 符合 RFC3986，并考虑到上述指导意见。

​
错误处理

服务器应该为常见的失败情况返回标准的 JSON-RPC 错误
  • 找不到资源：-32002
  • 内部错误：-32603
错误示例 
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

​
安全注意事项

  1. 服务器**必须 (MUST)** 验证所有资源 URI。
  2. 对于敏感资源，**应该 (SHOULD)** 实施访问控制。
  3. 二进制数据**必须 (MUST)** 进行正确编码。
  4. 在操作前，**应该 (SHOULD)** 检查资源权限。