一句话总结
⭐ 核心结论:我们的 MCP 网关把官方推荐的"渐进式发现"放在网关里实现。网关只给模型一组固定工具;下游几十个服务器的能力,由网关事先抓取、存成快照、建好向量索引;对话时,模型先检索,再通过网关执行。Tool 这条路很快就跑通了,但接入 Resource 和 Prompt 时踩了三个大坑:跨用户数据泄露、执行逻辑其实是桩代码、Prompt 的 role 丢失。
系列说明
📌 这是"MCP 网关"系列的第二篇。文中用到的基础概念(Host/Client/Server、Tool/Resource/Prompt 及其控制方、分页、role、渐进式发现)在第一篇《MCP 基础:Tool、Resource、Prompt 与渐进式发现》中都有讲解,建议先读第一篇。
目录
- 1. 整体架构
- 2. 两层结构:模型能看到什么
- 3. 三条设计原则
- 4. 事前:网关代为发现
- 5. 事中:检索与执行
- 6. 一个完整的例子
- 7. 坑一:Resource 的数据怎么抓才对
- 8. 坑二:执行这一步原来是假的
- 9. 坑三:Prompt 的 role 丢了
- 10. 要不要做"混合模式"
- 11. 对照业界:还能借鉴什么
- 12. 本文涉及的标准条款与我们的落地
- 13. 文章总结
- 参考资料
1. 整体架构
flowchart LR
subgraph CLIENTS["客户端"]
H1[企业聊天助手]
H2[Claude Code / IDE]
H3[自动化 Agent]
end
AUTH[认证服务
OAuth 登录 · 签发 token]
subgraph REG[Registry]
GW[MCP 网关
6 个固定工具]
API[管理 API
注册 · 启用 · 刷新]
SYNC[向量同步
后台任务 + 兜底对账]
end
DB[(快照数据库
服务器配置 · 能力清单
权限 · 用户同意 · token)]
VEC[(向量索引
Tool / Resource / Prompt 文档)]
subgraph DS["下游 MCP 服务器"]
S1[GitHub]
S2[Google Drive]
S3[Jira]
S4[……几十个]
end
H1 & H2 & H3 -->|OAuth 登录| AUTH
H1 & H2 & H3 -->|Bearer token| GW
API -->|"抓取 */list"| DS
API --> DB
DB --> SYNC --> VEC
GW -->|检索| VEC
GW -->|权限 · 同意 · 凭证| DB
GW -->|以调用者身份执行| DS
| 组件 | 作用 |
|---|---|
| 认证服务 | 客户端通过 OAuth 登录,拿到访问网关的 token |
| MCP 网关 | 对模型暴露固定工具;负责检索、安全检查,并代为调用下游 |
| 管理 API | 注册、启用、刷新服务器。抓取下游能力清单就发生在这一步 |
| 快照数据库 | 保存每个服务器的能力清单(快照),以及权限、用户同意记录、每个用户的 OAuth token |
| 向量索引 | 由快照生成的检索文档;网关检索时只查这里 |
| 向量同步 | 快照变化后同步更新索引;失败时由后台对账任务兜底 |
⭐ 本节要点:网关承担了两个角色。对客户端来说它是一台 MCP 服务器(只提供固定工具);对下游来说它是一个 MCP 客户端(负责抓取清单和代为调用)。
2. 两层结构:模型能看到什么
网关只对模型暴露 6 个固定工具:
| 网关工具 | 作用 |
|---|---|
discover_servers |
检索 Tool、Resource、Prompt |
execute_tool |
执行 Tool |
read_resource |
读取 Resource(具体 URI,或填好变量的模板) |
get_prompt |
获取 Prompt |
discover_agents / execute_agent |
A2A Agent(本文不涉及) |
整个系统因此分成两层:
flowchart TB
subgraph L0["客户端 + 模型"]
M["tools/list → 只有 6 个网关工具
resources/list、prompts/list → 空"]
end
subgraph L1["第一层:网关层(模型能直接看到)"]
D[discover_servers]
E[execute_tool]
R[read_resource]
P[get_prompt]
SEC["统一安全检查
认证 → 权限 → 禁用 → 用户同意"]
E & R & P --> SEC
end
subgraph BR["桥梁:快照 + 向量索引"]
IDX[(每个下游能力一条检索文档)]
end
subgraph L2["第二层:下游能力层(模型看不到)"]
S1["GitHub:create_issue · github://… · code_review"]
S2["Drive:… · gdrive://file/{fileId} · …"]
S3["…… 几十个服务器,几百个能力"]
end
M --> D & E & R & P
D -->|检索,只返回最相关的几条| IDX
L2 -->|事前抓取:操作人身份| IDX
SEC -->|实时请求:调用者身份| L2
和第一篇介绍的官方模式对照:
| 官方渐进式发现 | 我们的网关 |
|---|---|
search_tools 元工具 |
discover_servers |
固定的 call_tool 元工具(工具列表不变,对提示词缓存友好) |
execute_tool / read_resource / get_prompt |
| 由每个 Host 各自实现 | 集中在网关实现,所有客户端共用,同时统一做权限控制 |
📖 规范依据:官方《Client Best Practices》指出,需要按权限过滤时,应当自己实现检索,这正是网关的场景。Resources 规范也允许应用"根据启发式规则或 AI 模型的选择 自动纳入上下文",所以把 Resource 交给模型检索和读取,是规范允许的做法。
3. 三条设计原则
后面所有问题都能从这三条原则推导出来:
| # | 原则 | 推论 |
|---|---|---|
| 1 | 发现查的是快照,执行才实时调用下游 | 快照可能过时,需要刷新机制 |
| 2 | 抓取用"操作人"的身份,结果所有人共享;执行用"调用者"自己的身份 | 快照里只能存与具体用户无关的数据(见坑一) |
| 3 | 网关只能返回工具结果 | 下游的 Resource 和 Prompt 都要包装成工具结果,原生语义会丢失(见坑三) |
flowchart LR
subgraph FETCH["抓取:低频、操作人身份"]
A[管理员 Alice 点刷新] -->|Alice 的凭证| S[(下游服务器)]
S --> SNAP[(快照:所有人共享)]
end
subgraph EXEC["执行:每次调用、调用者身份"]
B[用户 Bob 的模型调用] -->|Bob 的凭证| S2[(下游服务器)]
S2 --> OUT[结果只给 Bob]
end
⭐ 本节要点:分清"什么时候拿数据"(事前还是实时)和"用谁的身份拿数据"(操作人还是调用者),是设计这类网关的关键。
4. 事前:网关代为发现
4.1 什么时候抓取
| 触发 | 用谁的凭证 | 说明 |
|---|---|---|
| 注册服务器 | 注册人 | OAuth 服务器在注册时跳过,因为此时还没有 token |
| 启用服务器 | 启用人 | 抓取失败会回滚为禁用 |
| 手动刷新 | 刷新人 | 更新已有服务器的唯一主动入口 |
| 联邦同步(如云厂商的 Agent 运行时) | 共享凭证 | — |
⚠️ 快照不会自动更新:目前没有定时刷新。下游能力变化后,要等有人刷新,快照才会同步。规范中的 listChanged 通知可以作为未来的触发手段。
4.2 从抓取到建索引的完整链路
sequenceDiagram
participant Admin as 管理员
participant API as 管理 API
participant S as 下游服务器
participant DB as 快照数据库
participant SYNC as 向量同步
participant VEC as 向量索引
Admin->>API: 刷新 GitHub 服务器
API->>S: 握手(自动协商协议版本)
API->>S: tools/list
API->>S: resources/list(分页拉完;OAuth 服务器不调用)
API->>S: resources/templates/list(仅当声明了 resources 能力)
API->>S: prompts/list(分页拉完)
API->>DB: 写入快照 + 标记"待同步"
API->>SYNC: 立即触发同步
SYNC->>VEC: 内容有变化 → 删除旧文档,重新向量化后写入
Note over SYNC,VEC: 同步失败时,后台对账任务按"待同步"标记重试
4.3 一个服务器会生成哪些检索文档
以 GitHub 服务器为例,每个能力生成一条文档,文本开头都带有服务器信息:
[tool] github | … | create_issue | 在仓库里创建一个 issue | Parameters: repo (string, required), …
[resource] github | … | URI: github://me/profile | MIME type: application/json
[resource] github | … | URI template: github://repo/{owner}/{repo}/readme | MIME type: text/markdown
[prompt] github | … | code_review | 按团队规范审查代码 | Required: language
下面两类内容会存入快照,但不进入索引:OAuth 服务器的具体资源,以及 MCP Apps 的 UI 资源(见第 7 节)。
5. 事中:检索与执行
5.1 检索:discover_servers
flowchart LR
Q["discover_servers(query, top_n, type_list)"] --> ACL[取出调用者有权访问的服务器]
ACL --> F["过滤:类型 ∈ type_list · 服务器已启用 · 工具未禁用"]
F --> B{query 为空?}
B -->|是| L["直接列出 top_n 条(普查,不排序)"]
B -->|否| H["混合检索:向量 + 关键词各占一半
召回 50–100 条候选"] --> RR[重排模型] --> TOP[取 top_n]
L & TOP --> RES["结果:entity_type · server_id ·
tool_name / resource_uri / resource_uri_template / prompt_name"]
⚠️ 几个容易误解的地方
type_list默认只有tool。模型不主动加上resource或prompt,就搜不到这两类。- 检索不分页:没有 cursor,默认返回 3 条,最多 50 条。找不到就换个关键词再搜。
- "只取最相关的"发生在检索阶段;执行阶段只执行模型选中的那一个。
- 资源类结果中,
resource_uri和resource_uri_template只会出现一个:前者直接使用,后者需要先填好变量。
5.2 执行:execute_tool 的 12 步
flowchart TB
S([execute_tool]) --> A1{1 token 有效?}
A1 -->|否| X1[isError:需要认证]
A1 -->|是| A2{2 服务器存在?}
A2 -->|否| X2["isError:server_id 已过时,请重新 discover"]
A2 -->|是| A3{3 有权限?}
A3 -->|否| X3[isError:无权访问]
A3 -->|是| A4{4 用户之前拒绝过授权?}
A4 -->|是| X4[isError:用户已拒绝,不要重试]
A4 -->|否| A5{5 工具被管理员禁用?}
A5 -->|是| X5[isError:已禁用,换一个]
A5 -->|否| A6{6 用户已同意?}
A6 -->|否| X6[请用户去浏览器确认同意]
A6 -->|是| A7[7 取调用者自己的 OAuth token 或 API key]
A7 --> A8[8 连接下游:使用缓存的协议版本]
A8 --> A9["9 tools/list 找到目标工具(用于校验输出)"]
A9 --> A10[10 tools/call]
A10 -->|401| RF[刷新 OAuth token 后重试一次] --> A10
A10 --> A11{11 下游要求用户输入?}
A11 -->|是| X7[转成文字提示]
A11 -->|否| OK([12 原样返回下游结果])
📖 规范依据:Tools 规范要求服务器 MUST 实施访问控制,并建议 SHOULD 始终保留"由人决定是否拒绝调用"的环节。第 3、5 步的权限和禁用检查对应前者,第 6 步的用户同意对应后者。
5.3 三种回应通道
| 通道 | 什么时候用 | 例子 |
|---|---|---|
工具结果 + isError: true |
模型自己能纠正的问题 | server_id 过时、工具被禁用、无权限 |
| 让用户去浏览器操作 | 需要用户本人处理 | 用户同意、OAuth 重新授权。新版协议返回 InputRequiredResult,旧版协议返回 -32042 错误;客户端不支持时,退化为一段文字提示 |
| JSON-RPC 错误 | 模型和用户都处理不了 | 下游宕机、超时、内部错误 |
💡 两条防护:客户端重试时,网关会重新检查用户同意和 token,不直接相信客户端声称的"已同意";同一项检查最多只提示一次,防止自动确认的客户端陷入死循环。
6. 一个完整的例子
sequenceDiagram
participant U as 用户
participant M as 模型(Host)
participant G as 网关
participant V as 向量索引
participant S as GitHub 服务器
U->>M: 在 anthropic/sdk 建个 issue:README 链接失效
M->>G: discover_servers("github create issue")
G->>V: 按权限过滤后检索
G-->>M: create_issue · server_id=abc · 参数 schema
M->>G: execute_tool(create_issue, abc, {...})
G->>G: 认证 · 权限 · 禁用检查 ✓ · 用户同意 ✗
G-->>M: 需要用户在浏览器确认同意(附链接)
M-->>U: 请打开链接确认
U->>G: 在浏览器中点击"同意"
M->>G: 用相同参数重试 execute_tool
G->>G: 重新检查全部通过 · 取出用户自己的 GitHub token
G->>S: tools/list → tools/call create_issue
S-->>G: issue #42 created
G-->>M: 原样返回
M-->>U: 已创建 issue #42
7. 坑一:Resource 的数据怎么抓才对
Tool 跑通之后,我们开始接入 Resource 和 Prompt。第一批问题都出在"事前抓取"这一步。
7.1 问题清单
| 问题 | 后果 | 修法 | 对应的标准 |
|---|---|---|---|
从不调用 resources/templates/list |
参数化资源(如"任意仓库的 README")完全搜不到 | 补上模板抓取,并且只有服务器声明了 resources 能力才请求 |
能力声明 MUST |
| 只取第一页 | 大服务器的资源被悄悄截断 | 按 cursor 拉完所有页;整个列表共用一个超时;cursor 重复时停止 | cursor 不透明 MUST |
| OAuth 服务器跨用户泄露 | 见 7.2 | 见 7.2 | 资源访问控制 SHOULD |
MCP Apps 的 UI 资源(ui://、text/html;profile=mcp-app) |
实际统计时,11 个已索引资源中有 9 个是这类 HTML,对模型毫无用处 | 照常存入快照,但不进入索引;比较 MIME 前先统一大小写、去掉空格 | MCP Apps 扩展 |
| 具体 URI 被标成 “URI template” | 模型会去"填空"一个根本没有变量的 URI | 具体资源标 URI:,模板标 URI template:,两个字段只出现一个 |
Resource 与 Template 的区分 |
| 一个列表失败就写入空值 | 一次网络抖动就把已有数据全部清空 | 失败时保留旧值;只有下游明确返回 -32601(不支持)才清空 |
— |
7.2 最严重的一个:跨用户泄露
根源在第 3 节的原则 2:抓取用的是操作人的身份。
flowchart LR
Alice[管理员 Alice 刷新 Drive 服务器] -->|Alice 的 OAuth token| GD[(Google Drive MCP)]
GD -->|resources/list 返回 Alice 的文件
salary.xlsx、合同.pdf……| SNAP[(快照)]
SNAP --> IDX[(向量索引)]
SNAP --> DETAIL[服务器详情页]
SNAP --> LOG[抓取日志]
IDX --> Bob[用户 Bob 检索时看到 Alice 的文件名]
DETAIL --> Carol[用户 Carol 在详情页看到]
style SNAP fill:#f8d7da
style LOG fill:#f8d7da
🚫 泄露的是"存在性":别人真去读这些文件时会被 OAuth 拒绝,但"Alice 有一个叫 salary.xlsx 的文件"这件事已经泄露了,而且日志里也打印了全部 URI。
修法:
flowchart LR
subgraph LAYER1["① 抓取时:根本不调用"]
O[OAuth 服务器] -.->|不发送 resources/list| X((×))
O -->|只抓模板和 prompt| SNAP2[(快照:resources = 空)]
end
subgraph LAYER2["② 建索引时:再过滤一次"]
SNAP2 --> IDX2[(索引:跳过 OAuth 服务器的具体资源)]
end
subgraph LAYER3["③ 返回时:再过滤一次"]
SNAP2 --> API2[详情接口:resources 返回空]
end
- 根本不调用,而不是"拉回来再丢掉",因为拉取过程中数据已经经过了内存和日志。
- 三层防护:即使旧版本程序在滚动发布期间把数据写了回去,也不会暴露出来。
- 日志只记录数量,不记录 URI。
- 写数据迁移:清理库里的历史数据,并触发索引重建。
⭐ 经验:凡是"用一个人的身份抓来、给所有人看"的数据,都要先问一句:这份数据和具体用户有关吗?
7.3 怎么验证:用真协议做端到端测试
单元测试用的是 mock,很容易出现"mock 接受任何参数,真实 SDK 却不认"的情况。我们差点就栽在一个分页参数名上:照着需求文档的写法会抛异常,而异常被一个宽泛的 except 吞掉,结果所有列表都静默变成空,mock 测试却全部通过。
所以我们另外写了一个端到端验证脚本:
flowchart LR
SCRIPT[验证脚本] -->|1 写入测试用户、服务器、权限、token| DB[(数据库)]
SCRIPT -->|2 调用真实刷新接口| API[管理 API]
API -->|3 真实 MCP 协议| FX["假下游服务器(FastAPI)
7 种场景 · 记录每个请求"]
SCRIPT -->|4 检查快照与详情接口| DB
SCRIPT -->|5 通过真实网关调用 discover_servers| GW[网关]
SCRIPT -->|6 断言:请求记录、快照、索引、日志| FX
7 种场景分别是:分页、两个协议版本、OAuth、未声明能力、列表报错、不再提供某个列表(-32601)、零工具服务器。断言按 MCP 规范逐条编写,例如"OAuth 服务器从未收到 resources/list"、“cursor 被原样回传”、“日志中搜不到任何资源 URI”。
⭐ 经验:涉及协议对接的功能,至少要有一条走真协议的端到端测试。
8. 坑二:执行这一步原来是假的
数据修好之后才发现,read_resource 和 get_prompt 其实是桩代码:不管传入什么,都返回写死的假数据,而且跳过了权限检查和用户同意。
⚠️ 上线顺序问题:数据修好后,资源更容易被检索到,模型拿到假数据的次数反而会增加。所以要么两件事一起上线,要么先发一个小修复,让这两个工具直接返回"暂不可用"。
修法是不再复制一份安全检查,而是把 execute_tool 的流程改成一条通用管道:
flowchart TB
T[execute_tool] --> OP1["ToolCall(name, args)"]
R[read_resource] --> OP2["ResourceRead(uri)"]
P[get_prompt] --> OP3["PromptGet(name, args)"]
OP1 & OP2 & OP3 --> AUTHZ["共用的安全检查
认证 → 服务器 → 权限 → 用户同意
(禁用检查只对 ToolCall 生效)"]
AUTHZ --> CALL["共用的下游调用
凭证 · 协议版本 · 401 刷新重试 · 错误映射"]
CALL -->|ToolCall| C1["tools/list → tools/call"]
CALL -->|ResourceRead| C2["resources/read(不走缓存)"]
CALL -->|PromptGet| C3["prompts/get(不走缓存)"]
C1 & C2 & C3 --> RENDER["各自的结果包装 → 工具结果"]
⭐ 经验:安全检查只能有一份。 两套几乎一样的代码,迟早会有一边漏掉某个检查,我们的桩代码就是现成的例子。
9. 坑三:Prompt 的 role 丢了
第一篇第 7 节讲过:Prompt 的消息带有 user / assistant role,直连时由 Host 按原 role 插入对话。经过网关之后,情况就不同了。
9.1 role 在哪一步丢失
flowchart LR
D["下游 prompts/get
messages = [user: 任务, assistant: 示范]"] --> G["网关内部
role 仍然完整"]
G --> W["包装成工具结果
CallToolResult 只有 content
没有放 role 的位置"]
W --> H["Host 把它当作『工具结果』
交给模型"]
style W fill:#f8d7da
两种方式下,模型看到的对话对比如下:
flowchart TB
subgraph DIRECT["直连:role 原样生效"]
A1["user:请审查代码,按三栏输出"] --> A2["assistant:好的,我会按表格输出"] --> A3["user:(代码)"] --> A4["assistant:▌ 延续表格格式"]
end
subgraph VIAGW["经过网关:全部变成工具结果"]
B1["user:用 code_review 模板审一下"] --> B2["assistant:调用 get_prompt"] --> B3["工具结果:(任务 + 示范,全部是外部数据)"] --> B4["assistant:▌"]
end
| Prompt 类型 | 影响 |
|---|---|
| 只有 user 消息(最常见) | 基本可用。用户刚要求使用这个模板,模型通常会照做,效果类似"按需加载一段说明" |
| 带 assistant 示范消息 | 示范作用明显变弱:模型不会认为这些是"自己说过的话" |
📖 规范依据:Prompts 规范中写道 “Prompts are designed to be user-controlled”,同时也说明协议不强制具体的交互方式。所以把 Prompt 交给模型去检索和调用,并不违反规范,但偏离了它的设计意图。规范还要求 MUST 严格校验 Prompt 的输入和输出,以防止注入攻击。
9.2 折中做法及其边界
我们在内容里给每条消息加上 [message 1: user]、[message 2: assistant] 这样的标记。这样做的边界要说清楚:恢复的只是"标签",不是"语义"。assistant 消息只能作为"示例"供模型参考。
🚫 这一点是有意为之:如果网关能让模型相信"下游给的这段话是你自己说的",那么任何一个接入的第三方服务器都可以操纵模型。
最初的设计里还有一句说明:"请把 user 消息当作用户的请求去执行。"这句话有两个问题:
- 等于网关替下游背书,下游可以借此冒充用户;
- 模型出于防注入的训练,可能直接忽略这句话。
更好的写法是只说明"这是什么":
以下是用户要求使用的模板 X 的内容,请按模板完成用户的请求;标为 assistant 的消息是示例回复。
9.3 根本解法
根因在第一篇讲过:role 由拼装消息的 Host 决定,网关做不到。所以根本解法只有一条:让 Host 按真实 role 把消息插入对话。
flowchart TB
ROOT["根因:只有 Host 能决定 role"] --> A["方式 A:网关原生暴露 prompts/get
用户在客户端点选 → Host 按 role 插入
标准做法,所有标准客户端都可用"]
ROOT --> B["方式 B:在工具结果的元数据里附上原始消息
自家客户端识别后按 role 重新插入
非标准约定,只对改造过的客户端有效"]
A & B --> SAFE["安全前提:只有用户明确选择了这个模板时,才按原 role 插入"]
⚠️ 常见误解:应该整体放进 assistant 吗? 不是。每条消息应回到它自己的 role:任务说明放 user,示范回答放 assistant。而且网关本身没有这个选择权,工具结果在消息数组中的位置是固定的。
⭐ 经验:协议里"谁来控制"的设定不是摆设。 把用户控制的 Prompt 交给模型调用,就要接受语义上的损失,并重新审视安全边界。
10. 要不要做"混合模式"
我们也考虑过混合模式:Tool 仍然走检索;同时网关原生暴露 prompts/list 和 resources/list,供客户端界面使用(斜杠菜单、@ 资源选择)。
flowchart LR
subgraph NOW["现在:只有一条路"]
M1[模型] -->|discover → get_prompt| G1[网关]
end
subgraph HYBRID["混合模式:两条路"]
M2[模型] -->|discover → 执行| G2[网关]
U2[用户] -->|"/ 菜单、@ 选择"| H2[Host] -->|"原生 prompts/get、resources/read"| G2
end
💡 关键认识:"只暴露 Tool"的理由只对 Tool 成立。tools/list 的内容会交给模型,所以数量不能多;prompts/list 和 resources/list 只用于渲染界面,不会进入模型的上下文。
| 现在 | 混合模式 | |
|---|---|---|
| 用户能看到有哪些 Prompt / Resource | ❌ | ✅ |
| Prompt 的 role | 只能写成文字标记 | ✅ 原样保留 |
下游返回的 resource_link |
❌ 读不到 | ✅ 改写 URI 后可以读取 |
| 模型上下文 | 6 个工具 | 不变 |
| 模型自己找工具的场景 | — | 没有任何改善 |
我们在本地实测过:一次带关键词的检索大约 1 秒,列一次目录只要几毫秒。在"用户自己知道要用哪个模板或资料"的场景里,混合模式每次能省下约 2 轮模型推理和 1 次检索(这是估算)。但最常见的"模型自己找工具"场景完全不受影响;而且我们自家的客户端会把每个 Prompt 转成一个工具,列表一大反而会撑爆上下文。权衡之后,暂时不做,先把当前方案做扎实。
⭐ 经验:评估一个方案时,先分清它解决的是哪个问题,再看这个问题在真实使用中占多大比例。
11. 对照业界:还能借鉴什么
第一篇第 9 节列出了业界常见做法。这里按设计维度和我们的网关逐项对比:
| 设计维度 | 业界做法 | 我们的现状 | 启发 |
|---|---|---|---|
| 检索时附带授权状态 | Composio 的搜索结果直接标明"是否已授权";Alexa 会先试探候选能否处理 | 执行时才发现需要同意或授权 | 在检索结果中标注授权状态 |
| 排序信号 | Alexa 重排时参考用户已启用的技能、使用记录等 | 只看文本相关度 | 加入使用记录、成功率等信号 |
| 检索与参数定义分离 | Composio 分搜索和获取 schema 两步;官方三层模式 | 检索结果直接带完整 schema(每条约 250 token) | 拆成两步,或提供精简模式参数 |
| 常用能力常驻 | Anthropic 建议常驻 3–5 个;Agentforce 按主题限定;ContextForge 虚拟服务器 | 没有 | 常用的直接挂出,长尾的走检索 |
| 分层检索 | Copilot 先选插件再选函数;MCP-Zero 先选服务器再选工具 | 平铺检索 | 服务器多了以后再加 |
| 点名调用与自动路由并存 | Alexa 两者都支持 | 只有自动路由 | 即第 10 节的混合模式 |
| 批量执行 | Composio 支持一次并行执行多个 | 一次一个 | 长期方向 |
后续改进按投入产出比排序:
flowchart LR
P0["P0 建立检索评测集
真实查询 → 正确能力
衡量召回率"] --> P1a["P1 检索结果带授权状态"]
P0 --> P1b["P1 重排加入使用信号"]
P0 --> P1c["P1 用大模型扩写能力描述"]
P1a & P1b & P1c --> P2["P2 常用常驻 · 检索与参数定义分离 · 混合模式"]
P2 --> P3["P3 分层检索 · 推理前预检索 · 批量执行 / Code Mode"]
💡 网关独有的优势:"授权状态"和"使用信号"这两项,只有网关才做得到:权限、用户同意、token、调用记录都在网关手里,单纯做检索的方案拿不到这些数据。
12. 本文涉及的标准条款与我们的落地
| 标准条款 | 级别 | 我们的落地 |
|---|---|---|
| 支持某项能力的服务器必须声明该能力 | MUST | 只有下游声明了 resources 才去抓取模板 |
| cursor 是不透明令牌,不解析、不修改;不假设页大小 | MUST | 抓取时原样回传 cursor,一直拉到没有 nextCursor;额外加了防重复和整体超时 |
| Tool 由模型控制,Resource 由应用驱动(可由模型选择),Prompt 由用户控制 | 设计意图 | Tool、Resource 交给模型检索和执行;Prompt 也交给模型,但接受语义损失,并修正说明措辞 |
| 服务器必须实施访问控制,必须校验输入、清洗输出 | MUST | 检索前按权限过滤,执行前再检查一次;三种操作共用一条安全管道 |
| 应保留"由人决定是否拒绝调用"的环节 | SHOULD | 首次调用需用户在浏览器确认同意;重试时重新检查 |
| 敏感资源应做访问控制,操作前检查权限 | SHOULD | OAuth 服务器不抓取具体资源,三层过滤 |
工具执行错误用 isError 返回,交给模型自我纠正 |
SHOULD | 模型可纠正的问题(server_id 过时、工具被禁用)都用 isError 返回,并附上下一步建议 |
| Prompt 的输入输出必须严格校验,防止注入 | MUST | 说明文字不声称"这是用户说的",assistant 消息只作为示例 |
| 工具多时采用渐进式发现,保持工具列表不变 | 最佳实践 | 网关只暴露 6 个固定工具,由 discover_servers 检索 |
ui:// 资源是交给宿主渲染的 HTML |
扩展定义 | 存入快照,但不进入索引 |
13. 文章总结
mindmap
root((MCP 网关))
架构
网关对上是服务器
网关对下是客户端
快照加向量索引做桥梁
三条原则
发现查快照 执行才实时
抓取用操作人身份
执行用调用者身份
只能返回工具结果
检索与执行
默认只搜 tool
不分页 只取最相关
12 步安全检查
三种回应通道
三个坑
OAuth 跨用户泄露
执行是桩代码
Prompt 的 role 丢失
取舍与方向
混合模式暂不做
授权状态进检索结果
使用信号进重排
先建评测集
⭐ 记住这五句话
- 网关就是放在服务端的渐进式发现:只给模型固定工具,先检索再执行,所有客户端共用一套权限控制。
- 分清时机和身份:发现查快照、执行才实时;抓取用操作人身份、执行用调用者身份。快照里只能存与用户无关的数据。
- 安全检查只写一份:三种能力共用一条管道,桩代码最容易绕过检查。
- Prompt 经过网关会丢失 role:能补回的只是标签;要恢复原生语义,只能让 Host 按 role 插入。
- 先量化再优化:建评测集、统计使用比例,再决定做混合模式还是检索改进。
13.1 经验清单
- 工具多了就别全塞给模型:先检索再执行,并保持工具列表固定不变。
- 分清"发现"和"执行":发现查快照,执行才实时调用;快照会过时,要有刷新机制。
- 分清"抓取身份"和"执行身份":用一个人的身份抓来、给所有人看的数据,只能是与用户无关的。
- 列表一定要处理分页:cursor 原样回传,防止死循环,整个列表共用一个超时。
- "失败"和"不支持"是两回事:失败时保留旧值,明确不支持(
-32601)时才清空。 - 对模型没用的内容不进索引(如 UI 资源),但可以照常存储。
- 安全检查只写一份:新功能复用同一条管道。
- 注意上线顺序:数据和功能分开上线时,确认中间状态不会让用户拿到假数据。
- 尊重协议中"谁来控制"的设计意图:改变控制方,就要接受语义损失并重新评估注入风险。
- 不要让工具结果冒充用户:说明文字只描述"这是什么"。
- 端到端用真协议验证:mock 会掩盖参数名、协议版本这类问题。
- 先量化,再优化。
参考资料
- 本系列第一篇:《MCP 基础:Tool、Resource、Prompt 与渐进式发现》
- MCP Client Best Practices(Progressive Discovery)
- MCP 规范:Tools、Resources、Prompts、Pagination
- MCP Apps 扩展
- Composio Meta Tools
- Amazon Science: HypRank
- Microsoft 365 Copilot 编排器
- Anthropic: Introducing advanced tool use
- AWS AgentCore Gateway semantic search
- IBM ContextForge
- ToolRet、MCP-Zero