AI Agent / 系统课时
提供 MCP 资源
提供 MCP 资源
本节把业务上下文通过 MCP Resource URI 暴露给客户端,让 Agent 能按资源标识读取数据,而不是把所有上下文硬编码进提示词。示例会实现一个按客户编号读取业务资料的资源,并说明资源与工具的职责边界。
学习目标
- 使用 Resource URI 为上下文建立稳定标识
- 用 MCPServer 注册动态资源模板并返回 JSON 文本
- 判断什么时候应该使用资源,什么时候应该改用工具
资源解决什么问题
MCP 资源适合表达“可以读取的上下文”,例如配置文件、运行手册、数据库查询结果或业务实体快照。客户端先知道有哪些资源或资源模板,再按 URI 读取具体内容;URI 负责定位,真正的数据仍由服务端在读取时生成或加载。

资源 URI 应稳定、可解释,并与底层存储解耦。customer://1001 可以映射数据库、缓存或远程服务;客户端不需要知道真实表名和文件路径,因此后端可以在不改变资源契约的前提下调整实现。
注册一个动态资源
保存为 customer_server.py。服务用 customer://catalog/{customer_id} 声明模板。当客户端读取 customer://catalog/1001,SDK 从模板取出编号。示例数据为虚构记录。真实服务要在读取时依据认证身份检查该编号的访问权。
import json
import sys
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("customer-resources")
CUSTOMERS = {
"1001": {"name": "Aster Labs", "tier": "pro", "status": "active"},
"1002": {"name": "Northwind", "tier": "basic", "status": "paused"},
}
@mcp.resource("customer://catalog/{customer_id}", mime_type="application/json")
def customer_profile(customer_id: str) -> str:
"""按客户编号返回只读客户资料。"""
customer = CUSTOMERS.get(customer_id)
if customer is None:
raise ValueError("customer not available")
# 返回稳定的文本序列化结果,便于客户端作为上下文读取。
return json.dumps(customer, ensure_ascii=False)
if __name__ == "__main__":
# 保持 stdout 专用于 stdio 协议,普通诊断信息写入 stderr。
print("MCP resource server ready: customer://catalog/{customer_id}", file=sys.stderr)
mcp.run(transport="stdio")预期输出
MCP resource server ready: customer://catalog/{customer_id}这行状态信息写入标准错误,进程随后会等待 MCP 客户端连接。从同目录运行 python probe.py customer_server.py --resource customer://catalog/1001。客户端先调用资源模板列表,再读取该 URI。读取时,资源正文对应以下内容;不同 SDK 可能在协议层附加 URI、MIME 类型等元数据,但业务文本应保持一致。
{"name":"Aster Labs","tier":"pro","status":"active"}这段 JSON 是资源内容的数据示例,不是要求客户端直接操作服务端内存。生产环境中可以把字典替换为数据库查询或文件读取,但资源函数仍应保持只读语义和清晰的错误处理。
设计 URI 与内容边界
资源 URI 不应直接泄露敏感物理位置,例如数据库连接串或服务器绝对路径。更稳妥的做法是使用业务命名空间,如 customer://1001、runbook://payments-timeout,由服务端负责把逻辑标识解析到真实数据源。
资源内容也不宜无限膨胀。若一个 URI 读取结果可能达到数十兆字节,应考虑拆成更细粒度的资源、增加分页式工具,或先暴露目录资源再按具体条目读取。这样既能减少上下文浪费,也便于权限控制和缓存。
验证资源是否可用
验证时至少覆盖三个点:客户端能识别资源或资源模板;读取合法 URI 能得到预期内容;不存在的标识会产生明确错误。对示例而言,customer://catalog/1001 应返回 Aster Labs 的资料,而 customer://catalog/9999 应失败,不能返回空对象掩盖数据缺失。
一个设计良好的 MCP 资源把“如何定位上下文”和“上下文存在哪里”分离开。Agent 只依赖稳定 URI 与返回内容,服务端则可以独立演进存储、权限和缓存策略。