MCP能力设计指南
3012 字约 10 分钟
AIAgentMCP设计
2026-07-24
一个外部能力究竟应该被设计成 Tool、Resource 还是 Prompt？这是 MCP 系统设计中最核心的设计决策之一。
一、基本定义
MCP 定义了三种核心能力类型，每种类型解决不同的问题：
- Tool：可执行的操作，模型选择并调用
- Resource：可读取的数据，提供上下文和信息
- Prompt：可复用的提示模板，定义交互结构
正确选择能力类型直接影响：
- 模型能否正确理解和使用能力
- 系统的安全性和可控性
- 用户体验和交互效率
- 系统的可维护性和可演化性
二、为什么需要设计指南
很多开发者在接入 MCP 时面临以下困惑：
- 搜索功能应该做成 Tool 还是 Resource？
- 配置信息应该通过 Resource 暴露还是 Tool 返回？
- 领域工作流应该用 Prompt 还是 Tool 组合？
- 一个能力同时涉及数据读取和操作时如何拆分？
错误的设计决策会导致：
- 模型无法正确选择工具
- 安全风险（将危险操作暴露为 Resource）
- 性能问题（将大数据量操作设计为 Tool）
- 用户体验差（重复的能力、不清晰的边界）
三、核心决策表
Tool、Resource、Prompt 判断矩阵
| 判断维度 | Tool | Resource | Prompt |
|---|---|---|---|
| 是否执行动作或计算 | 是 | 否 | 否 |
| 是否有副作用 | 可能 | 不应 | 不应 |
| 是否读取已有数据 | 可选 | 是 | 可引用 |
| 是否需要主动调用 | 是 | 是（按 URI） | 是（按名称） |
| 是否参数化 | 通常需要 | 可能需要 URI | 通常需要 |
| 是否返回结构化结果 | 通常 | 是 | 返回消息列表 |
| 是否适合模板化复用 | 较少 | 否 | 是 |
| 模型是否需要选择它 | 是 | 可选 | 是 |
快速决策流程
四、典型场景分类
适合设计为 Tool 的场景
| 场景 | 原因 |
|---|---|
| 创建或修改数据 | 有副作用，需要明确调用 |
| 执行搜索 | 需要参数，返回动态结果 |
| 发送消息或通知 | 有外部副作用 |
| 触发工作流 | 需要明确的触发点 |
| 执行计算 | 需要参数化输入 |
| 调用外部 API | 需要参数、认证和错误处理 |
| 删除操作 | 高风险，需要明确调用意图 |
适合设计为 Resource 的场景
| 场景 | 原因 |
|---|---|
| 读取文档或文件 | 纯数据读取，无副作用 |
| 获取配置信息 | 静态或半静态数据 |
| 获取 Schema 信息 | 结构性数据 |
| 读取数据库记录 | 通过 URI 定位数据 |
| 获取系统状态 | 当前状态的快照 |
| 提供上下文知识 | 注入模型上下文 |
适合设计为 Prompt 的场景
| 场景 | 原因 |
|---|---|
| 代码审查模板 | 可复用的交互结构 |
| 文档生成模板 | 参数化的生成流程 |
| 领域分析框架 | 可复用的思维结构 |
| 调试工作流 | 步骤化的交互模板 |
| 角色设定 | 预定义的行为模式 |
| 标准化输出格式 | 统一输出结构 |
五、边界案例分析
搜索功能
搜索是一个常见的边界案例：
| 设计方式 | 适用条件 |
|---|---|
| Tool | 搜索需要复杂参数（过滤、排序、分页）、返回动态结果 |
| Resource | 搜索等价于按 URI 读取一个已知查询的结果 |
建议：大多数搜索场景更适合 Tool，因为搜索通常需要参数化且结果动态变化。
配置信息
| 设计方式 | 适用条件 |
|---|---|
| Resource | 配置是相对稳定的结构化数据，需要被频繁读取 |
| Tool | 配置需要动态计算或依赖运行时参数 |
建议：静态配置适合 Resource，动态配置适合 Tool。
领域工作流
| 设计方式 | 适用条件 |
|---|---|
| Prompt | 工作流主要是交互模板，实际执行由模型 + Tool 完成 |
| Tool | 工作流需要确定性执行，不允许模型自行决策 |
| Tool 组合 | 工作流的每个步骤都是独立的 Tool |
建议：如果工作流的步骤是固定的且需要确定性执行，用 Tool；如果工作流更像是引导模型完成一组任务的模板，用 Prompt。
六、Tool 设计维度
当决定设计为 Tool 时，需要考虑以下维度：
粒度
| 粒度 | 优势 | 劣势 |
|---|---|---|
| 细粒度（原子操作） | 灵活组合、职责清晰 | 模型需要多步调用 |
| 粗粒度（复合操作） | 一次调用完成复杂任务 | 灵活性差、参数复杂 |
| 中等粒度 | 平衡灵活性和易用性 | 需要仔细设计边界 |
建议：从中等粒度开始，根据模型实际调用情况调整。
描述质量
好的 Tool 描述应该包含：
- 做什么：一句话说明功能
- 何时使用：适用场景
- 何时不使用：不适用的场景（防止误选）
- 参数说明：每个参数的含义和约束
- 返回值说明：返回什么、格式是什么
- 副作用说明：是否修改数据、是否有外部影响
- 错误情况：可能失败的场景
好的描述示例：
"搜索 Obsidian Vault 中的笔记。支持按标题、内容、标签搜索。
返回匹配的笔记列表，包含标题、路径和摘要。
不创建或修改笔记。如需修改请使用 update_note 工具。"
差的描述示例：
"搜索"参数设计
- 使用 JSON Schema 定义参数
- 必填参数和可选参数分开
- 参数命名清晰、一致
- 提供参数描述
- 限制参数值的范围（enum、minLength、maxLength 等）
- 避免过度复杂的嵌套结构
输出设计
- 结果应该结构化，便于模型解析
- 返回足够的上下文（但不过量）
- 错误信息应该可理解
- 大结果集需要分页
- 考虑 Token 消耗
安全性
- 识别是否有副作用
- 评估风险等级
- 是否需要用户确认
- 是否需要权限检查
- 是否幂等
七、Resource 设计维度
URI 设计
- URI 应该稳定且有规律
- 使用有意义的 URI scheme
- 支持 URI 模板简化发现
- 示例：
file:///docs/readme.md、db://users/123
数据类型
| 类型 | 说明 | MIME 类型 |
|---|---|---|
| 文本 | 纯文本、Markdown、代码 | text/plain, text/markdown |
| 结构化 | JSON、YAML | application/json |
| 二进制 | 图片、文件 | image/png, application/pdf |
缓存策略
- 静态资源可以长时间缓存
- 动态资源需要明确一致性语义
- 使用 listChanged 通知缓存失效
权限
- 不是所有数据都应该暴露为 Resource
- 敏感数据需要权限过滤
- 考虑数据脱敏
八、Prompt 设计维度
模板结构
一个 Prompt 模板应该包含：
- 名称和描述
- 参数定义（arguments）
- 消息列表（包含角色和内容）
- 参数占位符的替换规则
适用场景
- 可复用的交互模式
- 领域专家知识的结构化表达
- 标准化工作流入口
- 团队共享的最佳实践
安全约束
- Prompt 不应包含必须由程序强制执行的安全规则
- Prompt 注入风险需要考虑
- 参数不应被用于绕过系统安全策略
九、组合设计模式
模式一：Resource + Tool
Resource 提供上下文，Tool 执行操作。
KnowledgeOS MCP Server:
- Resource: 笔记内容（读取）
- Tool: 搜索笔记（执行搜索）
- Tool: 创建笔记（执行创建）模式二：Prompt + Tool
Prompt 定义工作流模板，Tool 执行具体步骤。
代码审查流程:
- Prompt: 代码审查模板（定义审查维度）
- Tool: 读取代码文件
- Tool: 提交审查意见模式三：Resource + Prompt
Resource 提供数据，Prompt 定义如何处理数据。
知识学习助手:
- Resource: 学习材料
- Prompt: 学习计划生成模板十、设计原则
- 职责单一：每个能力做一件事
- 语义清晰：名称和描述应该让模型准确理解用途
- 最小暴露：只暴露必要的能力
- 安全优先：高风险操作使用 Tool 并加入确认
- 幂等优先：设计时优先考虑操作的幂等性
- 一致性：命名、参数、返回格式保持一致
- 可测试性：每个能力都应该可以独立测试
- 渐进演化：从简单开始，根据使用反馈调整
十一、常见误区
- 把所有能力都设计为 Tool：数据读取更适合 Resource
- 忽视描述质量：描述质量直接影响模型选择准确性
- 粒度过粗或过细：需要在灵活性和易用性之间平衡
- 混淆 Tool 和 Resource：有副作用的操作用 Tool，纯数据用 Resource
- 忽视安全分级：不是所有操作都同等风险
- Prompt 承担安全逻辑：安全规则应该由程序强制执行
- 不测试模型选择：设计完成后需要测试模型是否能正确选择
十二、实践检查清单
十三、完整示例
以 KnowledgeOS MCP Server 为例：
| 能力 | 类型 | 职责 | 原因 |
|---|---|---|---|
| 搜索笔记 | Tool | 执行搜索操作 | 需要参数、返回动态结果 |
| 读取笔记 | Resource | 提供笔记内容 | 纯数据读取 |
| 创建笔记 | Tool | 创建新文件 | 有副作用 |
| 更新章节 | Tool | 修改笔记内容 | 有副作用 |
| 目录树 | Resource | 提供目录结构 | 静态数据 |
| 标签索引 | Resource | 提供标签列表 | 静态数据 |
| 生成知识文档 | Prompt | 文档生成模板 | 可复用交互结构 |
| 文档质量检查 | Prompt | 检查模板 | 可复用分析框架 |
十四、与其他概念的关系
- MCP Tool能力：Tool 的详细设计
- MCP资源模型：Resource 的详细设计
- MCP Prompt能力：Prompt 的详细设计
- MCP Server设计：Server 中的能力组织
- MCP能力发现：能力如何被 Client 发现
- MCP安全边界：能力设计的安全考量
- MCP与Agent协作：能力如何被 Agent 使用
十五、适用边界
本指南适用于：
- 设计新的 MCP Server
- 评估现有能力的设计合理性
- 重构能力边界和粒度
- 团队讨论能力设计方案
不适用于：
- 具体的协议实现细节
- 特定编程语言的 SDK 使用
- 业务逻辑的设计
十六、延伸思考
- 当模型能力持续提升时，Tool 的粒度策略是否需要调整？
- 是否可能出现新的能力类型？
- 如何实现能力的自动组合和编排？
- 如何评估描述质量对模型选择的影响？
十七、参考资料
- MCP 官方规范 - https://modelcontextprotocol.io/specification
- MCP 官方文档 - https://modelcontextprotocol.io/
- Tool Use 设计最佳实践 - https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview