一句话总结
⭐ 核心结论:MCP 定义了 AI 应用对接外部系统的统一方式。服务器对外提供三种能力:Tool(动作)、Resource(资料)、Prompt(模板),分别由模型、应用、用户决定何时使用。客户端先用 */list 拉取清单,再用各自的方法调用或读取。工具多到几十个服务器、几百个能力时,官方推荐改用渐进式发现:先检索,再加载,最后执行。
系列说明
📌 这是"MCP 网关"系列的第一篇,只讲标准本身和基础概念,不涉及具体产品。
- 第一篇(本文):MCP 的角色、三种能力、发现与使用流程、消息里的 role、工具过多时的标准做法。
- 第二篇:《MCP 网关实战:从发现到执行的设计与踩坑》,讲我们的网关如何落地这些概念,以及踩过的坑。
目录
- 1. 为什么需要 MCP
- 2. MCP 里的三个角色
- 3. 三种能力:Tool、Resource、Prompt
- 4. 一次连接的开始:握手与能力声明
- 5. 发现:把清单拉下来
- 6. 使用:三种能力各有各的方法
- 7. 消息里的 role:Prompt 为什么要带 user / assistant
- 8. 工具太多怎么办:渐进式发现
- 9. 业界常见做法
- 10. 规范要点速查
- 11. 文章总结
- 参考资料
1. 为什么需要 MCP
假设一家公司有 3 个 AI 应用(聊天助手、IDE 插件、自动化 Agent),要对接 4 个系统(GitHub、Jira、Google Drive、数据库)。没有统一协议时,每个应用都要为每个系统单独写一套对接代码:
flowchart LR
subgraph NOMCP["没有统一协议:3 × 4 = 12 份对接代码"]
A1[聊天助手] --- G1[GitHub]
A1 --- J1[Jira]
A1 --- D1[Drive]
A1 --- B1[数据库]
A2[IDE 插件] --- G1
A2 --- J1
A2 --- D1
A2 --- B1
A3[自动化 Agent] --- G1
A3 --- J1
A3 --- D1
A3 --- B1
end
MCP 的思路和 USB 类似:应用实现一次"MCP 客户端",系统实现一次"MCP 服务器",双方用同一个协议通信,对接成本从"相乘"降为"相加"。
flowchart LR
subgraph WITHMCP["使用 MCP:3 + 4 = 7 份实现"]
A1[聊天助手] --> P((MCP 协议))
A2[IDE 插件] --> P
A3[自动化 Agent] --> P
P --> G1[GitHub MCP 服务器]
P --> J1[Jira MCP 服务器]
P --> D1[Drive MCP 服务器]
P --> B1[数据库 MCP 服务器]
end
⭐ 本节要点:MCP 把"每个应用 × 每个系统"的点对点对接,变成"应用实现客户端、系统实现服务器"的标准化对接。
2. MCP 里的三个角色
| 角色 | 是什么 | 例子 |
|---|---|---|
| Host(宿主) | 用户直接使用的 AI 应用,负责和大模型对话 | Claude Desktop、Claude Code、Cursor、企业聊天助手 |
| Client(客户端) | Host 内部负责和某个 MCP 服务器通信的模块,每个服务器对应一个 | 由 Host 内置 |
| Server(服务器) | 对外提供能力的一方 | GitHub MCP 服务器、数据库 MCP 服务器 |
flowchart LR
U((用户)) --> H
subgraph H["Host:AI 应用"]
LLM[大模型对话]
C1[MCP Client 1]
C2[MCP Client 2]
end
C1 <-->|MCP| S1[MCP Server:GitHub]
C2 <-->|MCP| S2[MCP Server:Drive]
LLM <--> C1
LLM <--> C2
⭐ 本节要点:只有 Host 在和大模型对话。发给模型的消息怎么组织、每条消息是什么 role,都由 Host 决定,Server 无权决定。第二篇里我们遇到的"role 丢失"问题,根源就在这里。
3. 三种能力:Tool、Resource、Prompt
用 Python 的 FastMCP 框架写一个 GitHub 服务器,最直观:
from fastmcp import FastMCP
from fastmcp.prompts import Message
mcp = FastMCP("github")
# ① Tool:一个"动作"。模型传参数调用,服务器执行,可能改变外部数据
@mcp.tool
def create_issue(repo: str, title: str) -> str:
"""在仓库里创建一个 issue"""
...
return "issue #42 created"
# ② Resource:一份"资料"。用固定 URI 标识,读取时返回内容,只读
@mcp.resource("github://me/profile", mime_type="application/json")
def my_profile() -> str:
return '{"login": "alice", "repos": 37}'
# ③ Resource Template:URI 里带 {变量},代表"一类资料"
# (FastMCP 检测到 URI 含变量时,会自动注册为模板)
@mcp.resource("github://repo/{owner}/{repo}/readme")
def readme(owner: str, repo: str) -> str:
return fetch_readme(owner, repo)
# ④ Prompt:一份"提示词模板"。返回若干条消息,本身不执行任何操作
@mcp.prompt
def code_review(language: str) -> str: # 返回 str = 一条 role=user 的消息
return f"请以资深 {language} 工程师的标准审查下面的代码……"
@mcp.prompt
def code_review_with_example(language: str) -> list[Message]:
return [
Message(f"请审查下面的 {language} 代码,按『问题-原因-建议』三栏输出。"), # user
Message("好的,我会按『问题 | 原因 | 建议』的表格输出。", role="assistant"), # 示范回答
]
3.1 一句话区分
💡 Tool 是"动作",Resource 是"资料",Prompt 是"做事的模板"。
3.2 最重要的一张表:谁决定使用
MCP 规范为三种能力规定了不同的控制方:
| 能力 | 是什么 | 谁决定使用 | 类比 | 典型界面 |
|---|---|---|---|---|
| Tool | 动作,可能有副作用 | 模型 | 函数调用 | 用户看不到,由模型调用 |
| Resource | 只读资料,用 URI 标识 | 应用(含用户的选择) | 打开文件 | @ 资源选择器、“附加文件” |
| Resource Template | 带变量的 URI | 应用 | 带参数的 URL | 填好变量后附加 |
| Prompt | 消息模板 | 用户 | 斜杠命令 | /code_review |
flowchart TB
subgraph CTRL["控制方"]
M[模型] -->|自己决定调用| T[Tool]
A[应用 / 用户的附加操作] -->|决定把什么放进上下文| R[Resource / Template]
U[用户] -->|主动选择| P[Prompt]
end
📖 规范原文(MCP 2025-11-25):
- Tools:“Tools in MCP are designed to be model-controlled.”(Tools)
- Resources:“Resources in MCP are designed to be application-driven.”(Resources)
- Prompts:“Prompts are designed to be user-controlled.”(Prompts)
同时,三处原文都补充了一句:“the protocol itself does not mandate any specific user interaction model”。也就是说,"控制方"是设计意图,协议并不强制界面必须怎么做。例如 Resources 一节明确允许应用 “implement automatic context inclusion, based on heuristics or the AI model’s selection”,即可以由模型来选择要读取哪些资源。
⭐ 本节要点:控制方不只是一个分类。它决定了结果以什么身份进入对话(见第 7 节),也决定了谁来承担安全责任。
3.3 Resource 与 Resource Template 的区别
| Resource | Resource Template | |
|---|---|---|
| 列表方法 | resources/list |
resources/templates/list |
| URI | 具体地址:github://me/profile |
带变量:github://repo/{owner}/{repo}/readme |
| 适用场景 | 数量有限、能全部列出的资料 | 数量无限或参数化的资料(任意仓库、任意日期) |
| 读取方式 | 直接 resources/read |
先按 RFC 6570 填好变量,再 resources/read |
⚠️ 常见遗漏:只调用 resources/list 而不调用 resources/templates/list,会把所有参数化资源整类丢掉。
4. 一次连接的开始:握手与能力声明
客户端连上服务器后,第一步是握手:双方协商协议版本,服务器同时声明自己支持哪些能力。
sequenceDiagram
participant C as MCP Client
participant S as MCP Server
Note over C,S: 2025-11-25 版本:initialize 握手(有会话)
C->>S: initialize(客户端版本、客户端能力)
S-->>C: 协议版本 + capabilities: tools / resources / prompts
C->>S: notifications/initialized
Note over C,S: 2026-07-28 版本:server/discover(无状态)
C->>S: server/discover
S-->>C: 支持的版本 + capabilities
📖 规范原文:“Servers that support resources MUST declare the resources capability.” tools、prompts 的规定相同。反过来理解:服务器没有声明的能力,客户端就不应该去请求。
两个协议版本的差异可参考《MCP 2026-07-28 规范解读》。本文只用到一点:握手之后,客户端就知道服务器支持哪些能力。
5. 发现:把清单拉下来
握手之后,客户端用各个 */list 方法拉取清单:
sequenceDiagram
participant C as MCP Client
participant S as MCP Server
C->>S: tools/list
S-->>C: create_issue(含参数 schema)
C->>S: resources/list
S-->>C: github://me/profile
C->>S: resources/templates/list
S-->>C: github://repo/{owner}/{repo}/readme
C->>S: prompts/list
S-->>C: code_review(含参数说明)
5.1 分页:新手最容易漏的细节
清单很长时,服务器每次只返回一页,同时给出一个 nextCursor:
sequenceDiagram
participant C as MCP Client
participant S as MCP Server
C->>S: resources/list
S-->>C: 第 1 页 + nextCursor = "abc"
C->>S: resources/list(cursor = "abc")
S-->>C: 第 2 页 + nextCursor = "xyz"
C->>S: resources/list(cursor = "xyz")
S-->>C: 第 3 页(没有 nextCursor,表示结束)
📖 规范原文(Pagination):
- cursor 是不透明令牌(opaque token)。客户端 MUST 把它当作不透明值:不对格式做任何假设,不解析、不修改,也不跨会话保存。
- 每页大小由服务器决定,客户端 MUST NOT 假设固定的页大小。
- 客户端 SHOULD 把响应中缺少
nextCursor视为结果结束。
⚠️ 工程上的补充(规范未要求,但建议做):同一个 cursor 重复出现,说明服务器有 bug,此时应停止翻页,避免死循环;整个列表最好共用一个超时,而不是每页单独计时。
5.2 常见的错误处理
| 情况 | 含义 | 建议 |
|---|---|---|
JSON-RPC 错误 -32601(Method not found) |
服务器不支持这个方法 | 视为"没有",结果为空 |
| 超时、网络错误、服务器内部错误 | 这一次请求失败 | 保留之前的结果,稍后重试 |
🚫 不要把"失败"当成"没有":否则一次网络抖动,就会把已有的数据全部清空。
6. 使用:三种能力各有各的方法
sequenceDiagram
participant U as 用户
participant H as Host(含大模型)
participant S as MCP Server
Note over H,S: Tool:模型决定
H->>S: tools/call create_issue {repo, title}
S-->>H: CallToolResult:content = [text: issue #42 created]
Note over U,S: Resource:用户或应用决定
U->>H: 在 @ 列表里选 readme 模板,填 owner / repo
H->>S: resources/read github://repo/anthropic/sdk/readme
S-->>H: ReadResourceResult:contents = [text: README 内容]
Note over U,S: Prompt:用户决定
U->>H: 输入 /code_review,填 language = python
H->>S: prompts/get code_review {language: python}
S-->>H: GetPromptResult:messages = [role: user, content: …]
三种结果的结构:
| 结果类型 | 主要字段 | 说明 |
|---|---|---|
CallToolResult |
content(内容块列表)、structuredContent、isError |
内容块可以是 text、image、audio、resource_link、resource(嵌入资源)。没有 role |
ReadResourceResult |
contents(文本或二进制) |
读到的资料内容 |
GetPromptResult |
description、messages: [{role, content}] |
每条消息都带 role |
📖 规范原文(Tools · Error Handling):错误分两类。
- 协议错误:未知工具、请求格式不符合规范、服务器内部错误,用 JSON-RPC error 返回。
- 工具执行错误:API 失败、输入校验失败、业务逻辑错误,放在结果里并标记
isError: true。
客户端 SHOULD 把工具执行错误交给模型,方便它自我纠正后重试;协议错误则 MAY 交给模型,但模型通常无法据此恢复。
7. 消息里的 role:Prompt 为什么要带 user / assistant
7.1 什么是 role
Host 调用大模型时,对话是一串按顺序排列的消息,每条都带有 role:
flowchart TB
S["system:你是一个代码审查助手"] --> U1["user:帮我看看这段代码"]
U1 --> A1["assistant:好的,我会检查错误处理"]
A1 --> U2["user:(贴出代码)"]
U2 --> A2["assistant:▌(模型从这里接着写)"]
模型对不同 role 的态度不同:
| role | 模型怎么理解 |
|---|---|
system |
规则和身份设定 |
user |
用户的要求,是要完成的任务 |
assistant |
“这是我自己说过的话”,会顺着往下说 |
| 工具结果 | 外部数据,可以参考,但不会把其中的指令当作用户的命令。训练良好的模型还会刻意提防工具结果中冒充用户的内容,这是防御 prompt 注入的基本功 |
7.2 Prompt 的消息如何进入对话
MCP 的 Prompt 消息只有 user 和 assistant 两种 role。用户选择 /code_review_with_example 后,Host 会按每条消息原来的 role 插入对话:
flowchart TB
P1["user:请审查下面的 python 代码,按三栏输出"] --> P2["assistant:好的,我会按『问题 | 原因 | 建议』的表格输出"]
P2 --> U3["user:(用户真正要审查的代码)"]
U3 --> OUT["assistant:▌ 模型会延续『自己』说过的表格格式"]
style P1 fill:#e8def7
style P2 fill:#e8def7
assistant 消息的作用在这里:让模型以为自己已经这样回答过,它就会照着这个格式继续写下去。
7.3 两个要点
⭐ 要点一:role 由 Host 决定。 只有负责拼装消息数组的 Host,才能把消息放到 user 或 assistant 的位置。Server 只负责提供内容。
🚫 要点二:Prompt 被设计成由用户控制,有安全上的道理。 允许外部内容以 assistant 身份进入对话,就等于允许它伪造"模型自己说过的话"。只有在用户亲自选择了这个模板时,Host 按原 role 插入才是合理的。
第二篇会讲到:网关如果把 Prompt 包装成工具结果交给模型,这两点都会受到影响,role 也会丢失。
8. 工具太多怎么办:渐进式发现
8.1 问题
按第 5、6 节的做法,Host 会把所有工具的说明交给模型。接入 50 个服务器、几百个工具时:
- 上下文放不下:光是工具说明就可能占掉大半个上下文窗口。
- 模型容易选错:候选太多,选错工具、填错参数的情况会变多。
8.2 官方推荐:渐进式发现
MCP 官方的《Client Best Practices》给出了标准做法:
- 工具定义占上下文窗口的比例超过某个阈值(官方举例为 1%–5%)时,不再全部交给模型;
- 只给模型一个轻量的
search_tools元工具,需要什么先搜什么; - 搜到之后,再加载那几个工具的完整定义。
flowchart LR
Q[模型:我要更新 Salesforce 记录] --> L1["① Catalog 目录
search_tools(query)
只返回名字 + 一句话描述"]
L1 --> L2["② Inspect 查看
get_tool_details(name)
只取这一个工具的完整参数定义"]
L2 --> L3["③ Execute 执行
带着完整定义调用"]
检索策略可以是关键词(BM25、正则)、向量、子代理(让小模型挑选)或混合。官方特别指出:需要按领域定制排序,或需要按权限过滤时,应当自己实现检索。
📌 定位:渐进式发现出自官方的客户端最佳实践文档,不是协议的强制条款(不是 MUST)。规范层面的讨论(如给 tools/list 增加查询参数)目前还处于草案阶段。
8.3 容易被忽略的提醒:提示词缓存
⚠️ 大模型服务商会缓存提示词前缀,其中包括工具列表。对话中途增删工具会让缓存失效,代价可能比省下来的 token 还多。 官方建议:新发现的工具追加在缓存断点之后,不要重新排序;或者所有调用都走一个固定的 call_tool({name, args}) 元工具,让工具列表始终不变。
8.4 扩展到服务器级别
同样的思路也可以用在"服务器"这一级:维护一份服务器注册表,需要时再连接,用完就断开。
sequenceDiagram
participant M as 模型
participant H as Host
participant R as 服务器注册表
participant S as MCP Server
M->>H: search_available_servers("CRM")
H->>R: 查询
R-->>H: Salesforce 服务器(未连接)
M->>H: enable_server("salesforce")
H->>S: server/discover + tools/list
H-->>M: 已连接,可用工具……
Note over M,H: 任务完成后
M->>H: disable_server("salesforce")
9. 业界常见做法
"能力太多,先缩小范围再执行"并不是 MCP 独有的问题,各家都有自己的做法:
| 做法 | 代表 | 思路 |
|---|---|---|
| 工具检索 + 延迟加载 | Anthropic Tool Search Tool | 工具标记为 defer_loading,检索后每次加载 3–5 个;建议最常用的 3–5 个常驻 |
| 网关内置语义检索 | AWS AgentCore Gateway | 为所有工具建立向量索引,提供一个检索工具代替 tools/list |
| 按服务器动态接入 | Docker MCP Gateway | mcp-find 搜索目录,mcp-add 把整台服务器加入当前会话 |
| 按场景组合 | IBM ContextForge | 从多个服务器中挑选能力,组合成一台"虚拟服务器" |
| 元工具 + 授权管理 | Composio Tool Router | 把搜索工具、获取参数、管理授权、批量执行都做成元工具 |
| 先召回再重排 | Amazon Alexa 技能路由 | 先粗选候选,再结合用户习惯等上下文信号精排 |
| 先选主题再选动作 | Salesforce Agentforce、Microsoft 365 Copilot | 先选领域、插件或主题,再在小范围内选具体动作 |
| 用代码组合调用 | Cloudflare Code Mode、Anthropic code execution with MCP | 把工具转成代码 API,模型写代码,在沙箱中组合调用,中间结果不经过模型 |
💡 研究结论(ToolRet):通用的向量检索模型在"工具检索"上表现并不好。常见的提升手段有:用大模型扩写工具描述、扩展查询、分层检索(先选服务器,再选工具)、重排。
10. 规范要点速查
下表把本文涉及的标准条款集中列出,方便日后查阅。MUST 表示规范强制,SHOULD 表示规范建议,最佳实践 表示官方实践文档中的建议。
| 主题 | 要点 | 级别 | 出处 |
|---|---|---|---|
| 能力声明 | 支持 tools / resources / prompts 的服务器必须在握手时声明对应能力 | MUST | Resources 等 |
| 控制方 | Tool 由模型控制,Resource 由应用驱动,Prompt 由用户控制;协议不强制具体交互方式 | 设计意图 | Tools / Resources / Prompts |
| 分页 | cursor 是不透明令牌,不解析、不修改、不跨会话保存;不假设固定页大小 | MUST | Pagination |
| 分页结束 | 响应中缺少 nextCursor 即表示结束 |
SHOULD | 同上 |
| 资源模板 | 用 RFC 6570 URI 模板表示参数化资源 | 规范定义 | Resources、RFC 6570 |
| Prompt 消息 | 消息的 role 只能是 user 或 assistant |
规范定义 | Prompts |
| 工具错误 | 协议错误走 JSON-RPC error;工具执行错误在结果中标 isError: true,客户端应把后者交给模型 |
规范定义 / SHOULD | Tools |
| 服务器安全 | 服务器必须校验所有工具输入、实施访问控制、限流、清洗输出 | MUST | Tools · Security |
| 资源访问控制 | 敏感资源应做访问控制,操作前应检查权限 | SHOULD | Resources · Security |
| Prompt 安全 | 必须严格校验 Prompt 的输入和输出,防止注入攻击和越权访问 | MUST | Prompts · Security |
| 人工确认 | 对工具调用应当有人类参与,并能拒绝调用 | SHOULD | Tools · Security |
| 渐进式发现 | 工具定义占上下文比例过高时,改为先检索、再加载、后执行 | 最佳实践 | Client Best Practices |
| 缓存友好 | 不在对话中途改动工具列表,或改走固定的 call_tool 元工具 |
最佳实践 | 同上 |
| UI 资源 | ui:// 资源(text/html;profile=mcp-app)是交给宿主渲染的 HTML |
扩展定义 | MCP Apps |
11. 文章总结
mindmap
root((MCP 基础))
角色
Host 和模型对话
Host 决定 role
Client 一对一连接 Server
三种能力
Tool 动作 模型控制
Resource 资料 应用控制
Template 带变量的 URI
Prompt 模板 用户控制
发现
握手与能力声明
list 方法拉取清单
cursor 分页原样回传
不支持与失败要区分
使用
tools/call
resources/read
prompts/get 带 role
规模化
渐进式发现
目录 查看 执行
保持工具列表不变
检索 重排 分层
⭐ 记住这五句话
- Tool 是动作,Resource 是资料,Prompt 是模板,分别由模型、应用、用户控制。
- 只有 Host 和模型对话,消息的 role 由 Host 决定。
- 发现靠
*/list:先看能力声明,cursor 原样翻页,"不支持"和"失败"要分开处理。 - Prompt 的 role 是有意义的:user 是任务,assistant 是"我说过的话",所以 Prompt 需要由用户来触发。
- 工具多了用渐进式发现:先检索,再加载,最后执行,并保持工具列表不变。
下一篇《MCP 网关实战:从发现到执行的设计与踩坑》会讲:我们如何把渐进式发现放到网关里实现,以及接入 Resource、Prompt 时遇到的跨用户泄露、桩代码、role 丢失等问题。
参考资料
- MCP 规范:Tools、Resources、Prompts、Pagination
- MCP Client Best Practices(Progressive Discovery)
- MCP Apps 扩展、RFC 6570 URI Template
- Anthropic: Introducing advanced tool use、Tool search tool
- Anthropic: Code execution with MCP、Cloudflare: Code Mode
- AWS AgentCore Gateway semantic search、Docker Dynamic MCP、IBM ContextForge、Composio Meta Tools
- Amazon Science: HypRank、Microsoft 365 Copilot 编排器、Salesforce Atlas Reasoning Engine
- ToolRet、RAG-MCP、MCP-Zero