一句话总结

⭐ 核心结论:我们的 MCP 网关把官方推荐的"渐进式发现"放在网关里实现。网关只给模型一组固定工具;下游几十个服务器的能力,由网关事先抓取、存成快照、建好向量索引;对话时,模型先检索,再通过网关执行。Tool 这条路很快就跑通了,但接入 Resource 和 Prompt 时踩了三个大坑:跨用户数据泄露、执行逻辑其实是桩代码、Prompt 的 role 丢失。

系列说明

📌 这是"MCP 网关"系列的第二篇。文中用到的基础概念(Host/Client/Server、Tool/Resource/Prompt 及其控制方、分页、role、渐进式发现)在第一篇《MCP 基础:Tool、Resource、Prompt 与渐进式发现》中都有讲解,建议先读第一篇。

目录


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 丢失
    取舍与方向
      混合模式暂不做
      授权状态进检索结果
      使用信号进重排
      先建评测集

⭐ 记住这五句话

  1. 网关就是放在服务端的渐进式发现:只给模型固定工具,先检索再执行,所有客户端共用一套权限控制。
  2. 分清时机和身份:发现查快照、执行才实时;抓取用操作人身份、执行用调用者身份。快照里只能存与用户无关的数据。
  3. 安全检查只写一份:三种能力共用一条管道,桩代码最容易绕过检查。
  4. Prompt 经过网关会丢失 role:能补回的只是标签;要恢复原生语义,只能让 Host 按 role 插入。
  5. 先量化再优化:建评测集、统计使用比例,再决定做混合模式还是检索改进。

13.1 经验清单

  1. 工具多了就别全塞给模型:先检索再执行,并保持工具列表固定不变。
  2. 分清"发现"和"执行":发现查快照,执行才实时调用;快照会过时,要有刷新机制。
  3. 分清"抓取身份"和"执行身份":用一个人的身份抓来、给所有人看的数据,只能是与用户无关的。
  4. 列表一定要处理分页:cursor 原样回传,防止死循环,整个列表共用一个超时。
  5. "失败"和"不支持"是两回事:失败时保留旧值,明确不支持(-32601)时才清空。
  6. 对模型没用的内容不进索引(如 UI 资源),但可以照常存储。
  7. 安全检查只写一份:新功能复用同一条管道。
  8. 注意上线顺序:数据和功能分开上线时,确认中间状态不会让用户拿到假数据。
  9. 尊重协议中"谁来控制"的设计意图:改变控制方,就要接受语义损失并重新评估注入风险。
  10. 不要让工具结果冒充用户:说明文字只描述"这是什么"。
  11. 端到端用真协议验证:mock 会掩盖参数名、协议版本这类问题。
  12. 先量化,再优化。

参考资料