Google Cloud API Gateway 支持 MCP：创始人的 Agent 工具上线验收表

9 月 24 日，Google Cloud 宣布 API Gateway 公测支持 MCP。已有 OpenAPI 3.x REST 服务的团队，可以给接口规范加注解，在网关的 /mcp 端点把符合条件的操作呈现为工具。Agent 发起 tools/call 后，网关再把请求转成原来的 REST 调用。这确实减少了一层集成工作，却也让现有产品能力交到一个新的决策者手里：Agent。

因此，上线问题不是“Agent 连上了吗”，而是：哪些客户操作可以被发现、由谁调用、何时值得执行、出了问题能否撤回？Google 文档说明，tools/list 默认无需认证，而 tools/call 沿用对应 REST 操作的认证规则。还有一个容易遗漏的配置细节：为工具列表配置 JWT 时，使用的 MCP 对象形式会默认启用所有符合条件的操作，除非逐项排除。团队以为只是在保护目录，结果可能扩大了目录。

本文面向在现有应用中加入 Agent 的非技术创始人和小团队，尤其是产品里已有账号资料、订单、消息、退款或预约操作的团队。你会得到一张逐工具上线验收表、一个订单客服案例、六项故障演练，以及清楚的放行和暂缓条件。这不是说公测功能本身不安全，也不是说通过清单就能证明任何场景都安全。

这次发布提供了什么，也有哪些边界

Google 的发布说明介绍的是 API Gateway 的公测能力，而不是一套完整的 Agent 产品平台。团队为 OpenAPI 3.0 或 3.1 规范添加注解、部署 API 配置，再让 MCP 客户端连接 /mcp。网关支持发现工具和调用工具。调用仍然落到原有 REST 操作，因此该操作配置的 API key 或 JWT、配额和日志路径继续生效。对已经有稳定 API 的小团队，这意味着不必另维护一套 MCP 服务，就能先试一个受控用例。

但配置文档写明了具体边界：只有 GET、POST、PUT、PATCH、DELETE 可以暴露为工具；操作必须有后端和非空描述；可以逐操作改名或排除。公测限制还包括：不支持 MCP resources、prompts 和响应流；工具声明不输出 readOnlyHint 或 destructiveHint；HTTP 204 这类空响应操作不能暴露；复杂嵌套 schema 在工具发现结果里可能显示不完整；同一 API 配置不能同时启用 MCP 与 model routing。这些会直接影响产品流程，例如 Agent 看到的参数结构不全，或一个原本成功但返回空内容的操作根本没有出现在工具目录。

“公测”也应进入采购和上线判断。Google 文档写明其适用 pre-GA 条款，支持可能有限。负责人应问：行为变化能否承受，替代方案要花多少工作，谁有权限关闭暴露。官方发布证明功能存在，不等于某个应用的权限、界面文案、客服流程和用户结果已经验收。

先分清三个术语：发现、调用、用户授权

工具发现是 MCP 客户端通过 tools/list 获取工具名称、描述与参数 schema。目录会告诉 Agent 可以尝试什么；对不该知道这些内部能力的人，它也可能暴露系统结构。MCP 工具规范把发现与调用定义为两种不同请求，并说明工具通常由模型决定何时使用。 工具调用是客户端提交带名称和参数的 tools/call。在这次网关公测中，调用转为 REST 请求。网关认证可以拒绝没有凭据的请求，但认证成功并不能回答客户是否真的想执行、客服 Agent 是否拿对账号、结果是否如实告知。认证是必要条件，并非完整的产品承诺。 用户同意与业务授权则是产品在当下判断：这个用户能否对这个对象产生这个效果。合法的 API 凭据可能属于权限远大于客户的服务账号；自然语言指令也可能有歧义。OWASP 关于 Agent 权限过大的指引建议在下游系统按用户身份做权限检查，并对高影响操作要求人批准。MCP 规范也建议界面清楚展示暴露的工具，并允许人拒绝调用。这些是产品设计原则，不是打开网关选项后自动获得的保障。

评审时分别问三句：Agent 看得见吗？当前凭据执行得了吗？产品此刻应该允许执行吗？“原 API 已经有认证”最多回答第二句的一部分。

从客户任务出发，缩小工具目录

假设一家小型订单客服产品收到两类问题：“包裹到哪了？”以及“能改收货地址吗？”现有 API 包含 getOrderStatus、listOrders、changeAddress、cancelOrder、issueRefund，还包含内部用的 exportOrders。技术上最快也许是暴露所有符合条件的操作；产品上更稳妥的第一步，是只给试点客户开放“查看本人订单状态”。

先写一句客户任务：“登录用户可以查询自己某一订单的最新配送状态。”再写一句不做什么：“助手不能改变履约状态，也不能披露别人的订单。”这不是口号；工程师可以据此写排除测试，评审人也能据此拒绝多余的工具。Google 配置指南允许逐操作纳入或明确排除。目录越大，Agent 选错工具和意外越权的机会越多。

工具描述也不能只复制 REST 路由名。“获取订单”可能诱导 Agent 在退款、改地址或查询别人的订单时调用。更有用的描述说明用途、返回内容和禁止用途，例如：“查询已认证客户本人一笔订单的配送状态与预计到达时间；不得用于退款或修改地址。”真正的所有权检查仍须由后端执行；描述只能引导模型，不能成为权限边界。

第一版优先选择能产生价值的只读操作，并裁减返回字段。如果 REST 响应还包含地址、电话、付款标识或内部风控备注，应先做仅返回必要字段的产品接口，再交给 Agent。工具输出会进入 Agent 的工作上下文，也可能流向解释文本或日志。OWASP 的 MCP 安全清单把过度共享和“代理人混淆”列为独立风险；它们不等同于认证失败。

工具发现开关有一个容易漏掉的副作用

Google 在发布文章和文档中都说明：tools/list 默认不要求认证。这不意味着别人能调用受保护的 REST 接口，却可能公开工具名与参数结构。issue_refund、export_all_orders、override_risk_hold 一类目录项，即使调用失败，也泄露内部能力的形状。公开目录是否合适要看产品；对私有客服产品，匿名发现通常没有必要。

更隐蔽的是配置形式。文档指出，为 tools-list.security 使用 x-google-api-management.mcp 对象时，也会全局启用所有符合条件的 MCP 操作。假如团队此前靠逐操作纳入控制目录，后来只想“给发现接口加 JWT”，却不查看最终目录，就可能把其他 API 一同带进来。不想暴露的操作应明确设置 x-google-mcp-tool: false。这是官方说明的配置行为；实际暴露仍取决于规范内容和部署配置，不能据此声称每个用户都遇到了漏洞。

上线材料里要有前后目录差异。逐项列出工具名、参数 schema、服务对象、对应 REST 操作、只读还是写入。用无 token、过期 token、错误 audience、有效客户 token、有效内部 token 分别请求 tools/list，保存原始响应与状态码。Google JWT 文档解释 issuer、subject、audience、签发与到期声明；MCP 配置文档明确，保护发现接口必须使用一个 JWT 方案，不能用 API key。只有一张“认证正常”的截图不够。

调用工具时，仍要按用户和对象检查权限

Google 表示 tools/call 继承对应 REST 操作的认证策略，这是有用的一致性：MCP 不应绕出另一套网关规则。但应用层仍须决定这个用户能否访问这个对象。订单案例里，客户拿着有效 token，仍可提供别人的 orderId。内部客服服务账号可能本来就能读全部订单。验收要验证后端每次都建立用户与订单的关系，而不相信 Agent 在提示词里说“这是他的订单”。

权限表至少要有四列：操作者、操作、记录范围、是否需要确认。get_order_status 允许登录客户读取自己的订单，可不额外确认。change_address 只能在符合履约条件时修改，界面先展示旧地址与新地址。issue_refund 可以由客服提出，但需要另一名有权人员或受控流程批准。这是产品策略示例，并非 Google 网关自动实现的能力。

还要防止凭据混用。若所有工具都用同一个高权限后端身份，“客户 A 查询客户 B 的订单”即使网关认证通过，也可能泄露数据。MCP 授权规范讨论协议边界的授权；OWASP建议下游按真实用户和最小权限约束执行。将最终用户身份传入后端决策，或使用足够窄的凭据。用两个真实测试账号和一笔无关订单做跨账号测试；只要越权调用成功，功能就不能上线。

在界面上区分“回答”与“已执行”

“你的包裹正在运输”与“我已经改了地址”失败成本不同，界面必须让用户看出差别。只读结果应显示来源状态及更新时间（如果接口提供）；写入操作应展示对象、拟修改的具体内容，以及提交前取消的路径。提交后，用业务系统的确认记录给用户回执。不能让模型流畅的一句话成为操作完成的唯一证据。

还可能出现后端已提交，但工具返回超时；客户端重试后，用户不知道地址改了一次、两次还是没改。对有后果的写操作，工程实现应有幂等键或等效防重复机制、操作编号，以及读取权威最终状态的方法。创始人要验收的是：用户能知道发生了什么，客服能还原过程。这是由 REST 副作用推导出的应用设计要求，并非 MCP 自动提供的功能。

MCP 工具交互建议要求应用清楚呈现工具暴露与调用，并建议确认提示，但没有规定具体界面。确认页应围绕实际后果写，而不是围绕工具名写。“将订单 A-1042 的配送地址从 X 改成 Y”比“批准 change_address”容易理解。还要给出拒绝后的正常路径，以及最终状态不确定时的人工支持路径。

可直接拿去开评审会的逐工具上线收据

每个工具用一份简短记录。技术证据用链接附上，不要埋在部署聊天记录里。下表是可复用模板，内容是示例，不是 YBuild 或 Google 客户的真实验收结果。

字段	`get_order_status` 的示例验收证据
客户任务	登录客户查询自己一笔订单的配送状态
目录决定	客户侧 MCP 目录只出现 `get_order_status`
发现证明	匿名、过期与错误 audience 的 `tools/list` 被拒；有效 token 只看到批准的工具
调用证明	本人订单成功；他人订单与不存在的 ID 不泄露资料
返回字段	状态、承运商、预计到达时间、更新时间；不含地址、电话、付款资料和内部备注
用户呈现	助手说明状态更新时间，并提供普通客服转接
故障行为	超时或格式错误不会被说成已送达
运营安排	记录负责人、告警、配额、回滚配置及客服路径
批准	产品负责人和安全／工程评审人签核确切配置版本

实际评审表还应链接已部署的 OpenAPI 配置、测试记录，以及用户流程截图或轨迹。没有版本号的“通过”很脆弱，后续改 API 可能自动带入新操作。Google MCP 配置指南同时支持全局启用与逐项覆盖，因此每次部署都要比较最终目录，而不只看源文件 diff。MCP 规范允许工具目录变化；客户端也可能需要刷新缓存。收据必须写清上线时客户实际能发现什么。

对写入工具，额外加入用户确认、幂等、防重复、撤销、部分失败和最终状态核对。拿不出这些证据，就先不要把该操作纳入目录。这是一道针对具体能力的上线门槛，并非要求产品所有部分完美后，才允许试一个只读功能。

试点前做六项故障演练

一，匿名发现。对已部署端点无凭据请求 tools/list。若返回私有目录，不要以“反正调用受保护”为由放行。先决定目录是否本来就允许公开；若不允许，配置 JWT 并复测。官方文档明确建议生产环境保护发现接口。 二，目录扩张。在预发布 OpenAPI 中添加一个无害且符合条件的操作，用同样的安全配置部署，查看它是否自动出现。若 MCP 对象全局启用了它，团队就要证明逐项排除有效，或建立明确的目录审批流程。这项演练针对未来 API 增长，而不只针对今天的文件。 三，凭据合法但客户不对。用客户 A 的身份请求客户 B 的订单号。预期是拒绝且不泄露 B 的细节；如果“订单存在”和“不存在”的不同错误也泄露隐私，要一并处理。再用客服凭据测一次，确保客服的较大权限不会被客户侧 Agent 借用。 四，描述诱导。分别让 Agent 处理退款、改地址与状态查询请求。它只应在最后一种任务中调用状态工具。即使只读接口目前无害，误调用也意味着描述或产品指令边界有问题。OWASP MCP 安全清单指出工具描述和返回内容都可能影响模型行为，值得按产品文案审阅。 五，坏数据与不确定状态。让后端返回过期 ETA、缺失承运商、超时，以及夹带“忽略之前规则”文字的结果。助手应把结果当数据处理，避免自信地编造配送状态，并提供人工路径。OWASP MCP Top 10列出工具投毒和上下文提示注入。网关认证成功并不会清洗后端文本。 六，推出与撤回。在预发布关闭该工具，确认它从发现结果消失，也确认客户端不会继续调用缓存版本。测量变化传到真实测试客户端用了多久。若时间未知，就别向客户或客服承诺“即时撤销”。回滚只有被端到端观察过，才算一项可信的产品能力。

试点指标要衡量客户结果，而非只数调用次数

Google 的监控文档说明网关有请求／响应日志，并提供延迟、流量、错误指标。这是运营基础，却不能证明客户得到了正确答案。产品侧还需记录请求意图、选用工具、认证结果、客户看到的结果、纠正、转人工，以及原任务是否完成。不要为了做仪表盘就记录完整的私密响应。

试点看板可分四组。访问：匿名发现、拒绝调用、跨账号测试。可靠性：延迟、超时、错误格式、重复写入。用户价值：状态查询是否解决、转人工比例、用户纠正。范围：目录新增、描述修改、权限例外。每个比率都要抽样看实例。若助手用过时状态给出自信回答，让“解决率”上升，那不是产品进步。

配额也不能只看 Agent。Google 的配额说明指出，配额在 API 配置中定义，却作用于整个 API；新配置可能影响仍在运行的其他网关。原本想保护 Agent 试点的改动，也可能拖累普通应用客户端。先定流量预算，演练触限行为，同时观察 MCP 与 REST 用户。负责人应知道 Agent 在高峰消耗共享容量时找谁处理。

哪些团队适合现在试，哪些应暂缓

已有持续维护的 OpenAPI 3.x 服务、逐操作认证明确、只想开放少量高价值任务，并且有人能核对实际部署目录的团队，适合考虑这条路线。尤其适合低风险只读任务：界面能交代不确定性，出错时有人工支持。若产品依赖 MCP resources、prompts、流式响应、复杂嵌套 schema 的完整发现、空响应操作，或同一配置中的 model routing，就要正视已写明的公测限制。

若用户所有权只靠提示词判断、服务凭据绕开用户范围、确认页说不清具体后果，或重试可能重复产生副作用，写入操作应暂缓。若团队拿不到最终工具目录，也无法在事故时撤回暴露，整个试点应暂缓。某些场景可能更适合独立 MCP 服务或其他网关，但同样需要产品层验收。“不用另建服务器”节省的是集成工作，不会替团队承担对客户的承诺。

今天可以做的决定并不复杂：选一个客户任务，只暴露最小操作集，用真实角色同时测试发现和调用；写入能力等确认与恢复路径得到证明后再加入。Google Cloud 的公测降低了 REST 接入 MCP 的门槛。真正能让客户放心的，是团队明确知道 Agent 被允许做什么，并能向客户证明实际发生了什么。

参考资料