Google Cloud API Gateway 怎么把 REST API 接入 AI Agent？2026 教程

本周建议动作（2026 年 9 月 25 日）：先在测试配置中只开放一个低风险操作，逐项验证 tools/list 和 tools/call，通过读写权限与功能验收后再扩大范围。Google 于 2026 年 9 月 24 日宣布这项能力进入 Public Preview，目前仍应按预览服务评估。(Google Developers Blog 公告)

API 开发者：已有 REST 服务，想减少为 Agent 单独维护 MCP 服务的工作。
平台工程师：需要确认 OpenAPI、认证、配额和日志能否沿用。
AI 产品团队：希望接入业务 API，同时保留清楚的读写权限和上线门槛。

1先判断你要省掉什么：复用 REST 后端，不是改造业务逻辑

Google Cloud API Gateway 可以作为远程 MCP 服务，通过 HTTP 接收 MCP 请求，再把工具调用转换成对应的 REST 请求。它复用的是已有后端和网关策略；接口是否有清楚的输入语义、是否适合由 Agent 触发，仍然需要你自己检查。官方说明的预览能力包括 initialize、notifications/initialized、tools/list 和 tools/call，并不代表完整支持 MCP。(API Gateway MCP 概览)

注意：网关将 MCP 请求转换成 REST 请求，不会替你判断某个写操作是否应该交给 Agent，也不会自动把业务接口设计成适合 Agent 的工作流。

2先划定工具边界，再决定全局开放还是逐项开放

场景一：你想快速验证一组低风险读取操作。可以从文档级配置开启 MCP，但这会让符合条件的操作成为工具候选。Google 文档要求可暴露操作具备后端配置和非空描述；默认工具名称来自 operationId，描述则来自操作的 description 或 summary。

场景二：同一 API 同时有读取与写入操作。不要只看“是否能调用”，要先按操作设置暴露范围。给工具写清用途、参数含义和副作用；尤其是删除、付款、改写等操作，应明确由你的 Agent 编排层决定何时请求用户确认。网关配置可以筛选操作，但不能代替业务侧授权设计，也不能代替完整的 Agent 权限治理。

x-google-api-management:
  mcp:
    tools-list:
      security:
        agentJwt: []
  backends:
    orders:
      address: https://YOUR_BACKEND

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      description: 按订单编号查询订单状态。
      x-google-backend: orders
      x-google-mcp-tool:
        name: get_order
        description: 仅在用户询问订单状态时查询，不执行修改。

  /orders/{orderId}/cancel:
    post:
      operationId: cancelOrder
      description: 取消订单。
      x-google-backend: orders
      x-google-mcp-tool: false

这里用对象形式配置了 mcp.tools-list.security，同时明确把取消操作设为不暴露；这是因为配置 mcp 对象本身会开启符合条件操作的 MCP 暴露。若你不打算全局开放，就要逐项选择或显式排除。tools/list 的认证方案必须使用定义在 components.securitySchemes 中的 JWT；Public Preview 不支持用 API key 保护这个方法。(MCP 配置说明)

3认证和策略沿用，但工具发现要单独设防

场景三：你希望继续使用现有 API key、JWT、配额和日志。tools/call 会按对应 REST 操作的 OpenAPI 安全规则验证身份，客户端调用时仍要提供该操作要求的凭据。工具发现是另一条边界：默认未认证的 tools/list 会暴露工具名称和输入结构；生产环境应另行配置 JWT 认证。初始化方法也不要求认证，所以不能把“保护了调用”误当成“所有入口都已受保护”。(MCP 配置说明)

已有策略能降低重复配置工作，却不能推导出一套完整的 Agent 授权体系。比如，你需要明确 Agent 使用哪个调用身份、这个身份能否访问敏感数据，以及一次工具调用如何关联到业务用户。配额也值得单独复核：Google 文档说明，新 API config 声明的配额指标和限制会作用于整个 API，而不只影响新配置；更改或移除指标前，应检查仍在运行的配置。(API Gateway 配额说明)

网关请求日志可用于检查状态码、延迟和请求处理情况，但这不等于日志里自动包含足够的业务审计上下文。你还应确认后端日志能否关联实际用户、Agent 身份和操作结果。(API Gateway 平台日志说明)

4按这条里程碑路径完成一次受控接入

第一步：确认规格和后端映射。核对文件是 OpenAPI 3.x，并确认目标操作的 x-google-backend 或全局后端配置有效。若还在使用 OpenAPI 2.0，先迁移规格，不要跳过版本核查。

第二步：先选少量操作。从只读、低影响的操作开始；写操作需要明确输入意义和副作用。检查描述是否足以让模型选择工具，而不只是重复接口名。

第三步：配置工具和身份边界。用 x-google-mcp-tool 逐项开放或排除操作；单独为 tools/list 配置 JWT，并分别验证工具发现身份与工具调用身份。不要假设同一份凭据会自动满足所有方法的要求。

第四步：创建 API config 并部署。部署过程使用现有 API Gateway 工作流。使用命令行时，Google 文档提醒 OpenAPI 3.x 上传前应更新 Google Cloud CLI 组件；创建新的 API config 后，部署前也要确认所在项目与配额配置。(创建 API config 的官方步骤)

第五步：按 MCP 握手和工具调用顺序测试。先发 initialize，再发送 notifications/initialized，随后验证 tools/list 是否只返回预期工具，最后分别用无效和有效凭据测试 tools/call。官方配置说明的 MCP 入口为网关 URL 下的 /mcp；路径或版本前缀以你的部署配置为准。

第六步：做后端回归与可观测性检查。确认工具参数按规格映射到路径、查询参数和请求体，并观察网关状态码、延迟及后端副作用。MCP 错误可能以 HTTP 成功响应承载 JSON-RPC 错误对象，因此不要只用 HTTP 状态码判断调用成功。

作为接入前的硬性核对项，Public Preview 每个 Gateway 最多支持 1,000 个 MCP 工具，可暴露的 HTTP 方法为 GET、POST、PUT、PATCH、DELETE；HEAD、OPTIONS、TRACE 不在支持范围内。规格上传还受 10 MB 总文件大小和 50 个文件的限制。(OpenAPI 3.x 限制清单)

5再看客户端和调用模式：ADK 示例不等于所有客户端通用

场景四：你的 Agent 使用 ADK 或其他 MCP 客户端。客户端连接网关的远程 MCP 入口，按网关配置提供所需凭据，再调用发现到的工具。Google 的 ADK 示例采用 McpToolset 和 StreamableHTTPConnectionParams；你可以照官方示例核对连接方式，但不要据此推断所有 MCP 客户端都支持相同传输、请求头或身份验证方式。(Google Developers Blog 中的客户端示例)

Agent 负责规划任务、选择工具并处理结果；API Gateway 负责请求校验、认证、MCP 与 REST 转换以及转发。工具说明写得含糊时，网关不会替你改善模型的选择质量；客户端无法提供所需 JWT 或 API key 时，也不能仅靠部署成功判定链路可用。

场景五：业务依赖流式或长时间工具调用。先查预览能力是否覆盖真实请求形态。当前限制包括不支持 SSE 长任务流式调用、MCP 资源和提示、stdio 传输，以及 JSON-RPC 批量请求；二进制工具响应也不受支持。此外，响应为空的操作（例如 HTTP 204）存在限制，且同一 API 配置不能同时启用 MCP 与 Model Routing。(API Gateway MCP 概览)

如果你的接口依赖长任务、二进制返回或资源与提示，先保留现有自建实现并做独立回归；仅在这些能力不是上线条件时，才把预览网关纳入候选。预览阶段的支持范围可能变化，验证结果应记录对应配置和测试日期。

6用准入条件决定继续试接，还是回退

• 若服务已经是 OpenAPI 3.x，操作能用普通 HTTP 请求表达，且不需要流式或 MCP 资源、提示：选 API Gateway 做小范围预览接入。
• 若 tools/list 身份校验、工具调用身份或读写边界尚未验证：先留在测试环境，不要给生产 Agent 开放。
• 若操作描述不足、写操作无法可靠限制，或调用要依赖长任务和二进制返回：先改造接口或保留自建 MCP 服务，不要把预览链路当成等价替代。
• 若团队需要完整的 Agent 编排、用户级授权或审批策略：由 Agent 平台与业务权限层承担这些职责，API Gateway 只作为接入与转发环节。

7常见问题：版本、认证与功能边界

Google Cloud API Gateway 的 MCP 能力目前仍为 Public Preview。若你的 REST 服务符合 OpenAPI 3.x，且目标只是让 Agent 调用有限的普通 HTTP 操作，可以在测试配置中先验证；如果接入条件依赖流式、长任务或完整权限治理，就应保留原方案，等需求与能力匹配后再迁移。

8你的下一步：把 API 网关和 Apple 执行环境分开验收

纯粹把业务 REST API 暴露给远程 Agent，不需要为了 MCP 网关额外租 Mac；API Gateway 处理的是远程 API 工具调用。若你的工作流还要构建或测试 macOS、iOS 客户端，本地 Linux 或容器执行环境则无法直接替代依赖 Xcode 的 Apple 工具链，另行验收 Mac 环境才有意义。Apple 官方列出的 Xcode 系统要求也以受支持的 macOS 版本为前提。(Apple Xcode 系统要求)

若你还在梳理 API 接入后的客户端构建与交付流程，可先从相关指南文章查找适合团队的执行环境说明；需要了解使用和交付问题时，也可查看帮助说明。自己长期维护一台 Mac，会带来设备采购、系统维护和闲置时段成本；临时拼接团队成员的本地机器，则容易遇到环境不一致、凭据分散和交付步骤不统一。

若只是阶段性联调或构建测试，可比较 Mac 环境租赁方案；若项目长期高强度运行，或必须连接特定物理设备，自购设备通常更合适。

最后更新于 2026 年 9 月 25 日；核实自 Google 于 2026 年 9 月 24 日发布的公告及 API Gateway MCP 配置、认证与限制文档。