1. 从 REST 到 Agent 工具为什么原生 MCP 值得关注Google Cloud API Gateway 原生支持 MCP 这件事核心价值可以用一句话说清楚你现有的 REST 接口只要在 OpenAPI 描述里加几个注解网关自己就变成了一个远程 MCP ServerAgent 可以直接发现并调用这些工具。不需要再单独写一个 MCP 中间层不需要复制鉴权、限流、日志逻辑也不需要维护两套入口。过去要把内部 REST API 暴露给 Agent最常见的做法是再写一个 MCP Server。这个中间层负责定义 tools/list、接收 tools/call、把参数转换成 REST 请求再复制一遍鉴权、限流、日志和错误处理。功能能跑但同一条业务能力从此出现两套入口普通客户端走 RESTAgent 走 MCP。时间一长策略漂移几乎是必然的——REST 那边改了配额MCP 这边忘了同步REST 那边加了新字段MCP 的 schema 还是旧的。Google Cloud API Gateway 这次的做法是把 MCP 请求直接转译成已有 REST 请求。Agent 对/mcp发出标准 JSON-RPC 的tools/call后网关根据工具定义找到对应 operation再把 arguments 映射回 path、query、body 或 header最终仍走原来的后端。原 REST operation 已经配置好的 JWT、API Key、quota 和 logging 不需要在 MCP 层重写。MCP 流量和 REST 流量进入的是同一条策略路径也共用同一个配额分配。对生产系统来说这比“少起一个容器”更有价值因为权限和审计只有一个事实源。你不需要回答“这个 Agent 调用到底走的是哪套鉴权”这种问题因为它走的就是原来那套。当前 Public Preview 要求 OpenAPI 3.0.x 或 3.1.xOpenAPI 2.0 不能直接启用。文档级可以用x-google-api-management.mcp开启 MCP单个 operation 再通过x-google-mcp-tool定义工具名和给模型看的描述。这里的 description 不应只写“返回订单状态”而应该明确告诉模型什么场景下应该调用它。这篇文章会带你走完一次真实工具调用闭环从 OpenAPI 注解配置、网关部署、MCP 工具声明到用 Python 发 JSON-RPC 请求验证 tools/call再到通过 TaoToken 统一 Key 和 API 通道接入。目标不是让你“了解这个功能”而是让你在自己的 GCP 项目里跑通一次。适合谁看已经有 API Gateway 和 OpenAPI 描述、想把现有 REST 接口低成本暴露给 Agent 的后端或平台工程师。如果你还在用 OpenAPI 2.0需要先升级到 3.0.x 或 3.1.x。2. TaoToken 前置准备统一 Key 与 API 通道在开始配置 Google Cloud API Gateway 之前先把 TaoToken 的接入信息准备好。TaoToken 在这里的角色是统一 Key 和 API 通道——你不需要为每个模型或每个 Agent 客户端单独管理一套凭证而是通过一个入口完成模型对话、coding plan 和 API 调用。官网地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点是https://taotoken.net/api。注意 API 地址不加 UTM 参数直接使用即可。你需要先拿到 API Key。进入控制台的 API Keys 页面https://taotoken.net/console/api-keys创建一个新的 Key。这个 Key 后面会用在两个地方一是作为 MCP 网关请求的x-api-keyheader二是作为 TaoToken 模型调用的凭证。如果你打算用 Claude Code 或类似的 coding agent 来消费这些 MCP 工具可以在 TaoToken 的 ClaudeCodeAnthropic 接入页https://taotoken.net/claude-code-anthropic找到对应的配置说明。对于长期编码和 Agent 场景Coding Planhttps://taotoken.net/coding-plan提供了更稳定的调用配额。模型对话调试可以用https://taotoken.net/model-chat接入文档在https://taotoken.net/doc。这些地址在后续验证环节会用到。这里要强调一个关键点TaoToken 的统一 Key 不是用来替代 Google Cloud API Gateway 的鉴权。网关那边的 JWT 或 API Key 仍然由 GCP 管理TaoToken 的 Key 是你在 Agent 侧调用模型和工具时的统一凭证。两者各司其职不要混在一起。准备好这些信息后你的配置清单应该是这样的项目值用途TaoToken API Key从 console/api-keys 获取Agent 侧模型调用和工具请求TaoToken API Basehttps://taotoken.net/api统一 API 通道GCP 项目 ID你的项目API Gateway 部署OpenAPI 文件已有或新建定义 REST operation 和 MCP 注解网关域名部署后获得MCP 端点地址把这些准备好接下来就可以进入 OpenAPI 配置环节。如果你还没有 GCP 项目或 API Gateway需要先在 Google Cloud Console 里启用 API Gateway 服务并创建一个网关。这部分是 GCP 标准操作不展开。3. 可复制配置OpenAPI 注解与网关部署这一节是整篇文章的核心操作部分。我会给出完整的 OpenAPI 片段、MCP 工具声明示例以及网关部署命令。你可以直接复制修改。先看 OpenAPI 文档级的 MCP 开启配置。在openapi.yaml的根级别添加openapi: 3.0.3 info: title: Order Service API version: 1.0.0 description: 订单查询与售后接口 x-google-api-management: mcp: enabled: true paths: /orders/{orderId}: get: operationId: getOrderStatus summary: 查询订单状态 description: 根据订单 ID 返回当前订单状态、支付状态和预计送达时间。适用于用户询问订单进度时调用。 parameters: - name: orderId in: path required: true schema: type: string description: 订单唯一标识格式如 A-1042 x-google-mcp-tool: name: get_order_status description: 查询指定订单的当前状态。当用户询问订单进度、是否发货、预计到达时间时使用此工具。需要提供订单 ID。 responses: 200: description: 订单状态 content: application/json: schema: type: object properties: orderId: type: string status: type: string enum: [pending, paid, shipped, delivered, cancelled] estimatedDelivery: type: string format: date-time 404: description: 订单不存在这里有几个关键点。x-google-api-management.mcp.enabled是文档级开关设为true后网关才会处理 MCP 请求。x-google-mcp-tool是 operation 级注解name是 Agent 看到的工具名description是给模型看的调用说明。description 的写法很重要。不要只写“返回订单状态”而要写清楚“什么场景下应该调用”。模型依赖这段描述来判断是否选择这个工具。我试过把 description 写得太简略结果 Agent 经常在不需要查订单的时候也去调这个工具。再看一个带 POST body 的写操作示例/support/tickets: post: operationId: createSupportTicket summary: 创建售后工单 description: 为指定订单创建售后咨询工单。当用户明确要求售后、投诉或咨询订单问题时使用。此操作会产生新记录。 x-google-mcp-tool: name: create_support_ticket description: 创建售后工单。仅在用户明确要求售后或投诉时调用。需要订单 ID 和问题描述。此操作会写入新数据。 requestBody: required: true content: application/json: schema: type: object required: [orderId, reason] properties: orderId: type: string description: 关联订单 ID reason: type: string description: 问题描述至少 10 个字符 responses: 201: description: 工单创建成功写操作的 description 要更严格明确说明“会产生新记录”让模型知道这是有副作用的操作。配置好 OpenAPI 后部署到 API Gateway。假设你已经有一个 API config 和 gateway更新命令如下gcloud api-gateway api-configs create order-mcp-config \ --apiorder-api \ --openapi-specopenapi.yaml \ --projectyour-project-id \ --backend-auth-service-accountyour-sayour-project.iam.gserviceaccount.com gcloud api-gateway gateways update order-gateway \ --apiorder-api \ --api-configorder-mcp-config \ --locationus-central1 \ --projectyour-project-id部署完成后网关会在域名下提供/mcp端点。你可以用gcloud api-gateway gateways describe查看网关地址。注意一个配置约束MCP 和 model routing 目前不能同时启用在同一个 API config。如果你已经在用 API Gateway 做模型路由需要先拆清楚配置边界不要直接在原配置上追加 MCP。另外返回 HTTP 204 的 operation 不会被暴露为工具过深的嵌套 schema 在 tools/list 中可能无法完整呈现单个网关最多暴露 1000 个工具。这些边界在规划工具集合时要提前考虑。4. 验证请求端到端调用与成功结果部署完成后第一步是验证 tools/list确认网关正确识别了 MCP 工具。用 curl 发一个 JSON-RPC 请求curl -X POST https://your-gateway-url/mcp \ -H content-type: application/json \ -H MCP-Protocol-Version: 2025-11-25 \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }如果配置正确你会看到类似这样的返回{ jsonrpc: 2.0, id: 1, result: { tools: [ { name: get_order_status, description: 查询指定订单的当前状态。当用户询问订单进度、是否发货、预计到达时间时使用此工具。需要提供订单 ID。, inputSchema: { type: object, properties: { orderId: { type: string, description: 订单唯一标识格式如 A-1042 } }, required: [orderId] } } ] } }这里有一个容易被忽略的安全细节当前 API Gateway 的 tools/list 默认不要求认证。只要知道 MCP 端点客户端可能先看到网关公开了哪些工具、工具参数长什么样。真正执行 tools/call 时底层 operation 原有的 JWT、API Key 等认证仍会生效但工具目录本身是否应该公开要单独做决定。如果工具名称、参数结构或描述包含内部业务信息生产环境更稳妥的做法是给 MCP 的工具发现启用 JWT。Google 文档同时明确指出API Key 不能用来保护 tools/list所以不能把“REST 接口已经要求 API Key”直接等同于“工具目录也已经受保护”。接下来验证 tools/call。下面这段 Python 可以直接运行不依赖任何 Agent 框架import os import requests url os.environ[MCP_GATEWAY_URL] api_key os.environ[API_KEY] payload { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: get_order_status, arguments: {orderId: A-1042}, }, } resp requests.post( url, headers{ content-type: application/json, MCP-Protocol-Version: 2025-11-25, x-api-key: api_key, }, jsonpayload, timeout20, ) resp.raise_for_status() print(resp.json())把MCP_GATEWAY_URL设置为类似https://xxx.uc.gateway.dev/mcp的真实地址API_KEY设置为你从 TaoToken 控制台获取的 Key。运行后如果返回订单状态数据说明 MCP 协议、网关转译、原 API 鉴权和后端返回四个环节全部打通。这段调用最适合放进发布前的连通性检查。如果 REST 接口本身已经在线那么新增 MCP 后不应该再出现一套完全独立的业务实现。如果你想通过 TaoToken 的模型对话来验证工具调用可以在https://taotoken.net/model-chat里配置 MCP 端点让模型实际选择并调用工具。这样能验证的不只是协议层还包括模型是否能正确理解工具描述并构造参数。验证通过后建议把这组请求做成回归脚本。测试样例不要只准备成功请求至少覆盖合法参数返回 200缺少必填参数被明确拒绝过期 JWT 无法执行不存在的资源返回稳定错误超过配额后得到可识别的限流响应。把这组请求固定下来比每次靠聊天窗口手工尝试更可靠。5. 常见报错排查401、local proxy failed 与 OAuth这一节对照真实报错给出排查路径。这些是我在实际配置过程中遇到或看到别人遇到的问题。401 Unauthorized这是最常见的报错。可能的原因有三个一是x-api-keyheader 没有正确传递检查你的请求是否带了 Key二是 Key 本身无效或已过期去 TaoToken 控制台确认 Key 状态三是底层 REST operation 的 JWT 认证失败MCP 层只是转译真正的鉴权还是由原 operation 的策略决定。排查顺序先用 curl 直接请求原 REST 接口确认原鉴权是否正常。如果原接口能通再检查 MCP 请求的 header 是否完整。注意MCP-Protocol-Version这个 header 不能少缺失时网关可能返回 400 而不是 401但容易被误判。local proxy failed这个报错通常出现在 Agent 客户端侧不是网关本身的问题。如果你在本地用 Claude Code 或类似工具连接 MCP 端点出现local proxy failed说明客户端到网关的网络链路有问题。检查网关地址是否可达确认没有把https://写成http://以及本地网络是否能访问 GCP 域名。如果你是通过 TaoToken 的统一 API 通道接入确认 API Base 设置为https://taotoken.net/api不要加多余的路径后缀。reading choices 相关报错这类报错通常出现在模型返回阶段提示无法解析 choices 字段。原因可能是模型返回格式与客户端预期不一致。如果你用 TaoToken 的模型对话调试确认请求的 model 参数和返回格式匹配。对于 MCP 工具调用场景模型需要支持 function calling 或 tool use不是所有模型都支持。OAuth 相关报错如果你给 tools/list 启用了 JWT 保护但客户端没有正确配置 OAuth token会看到 OAuth 相关错误。注意 API Key 不能用来保护 tools/list必须用 JWT。检查你的 token 是否包含正确的 audience 和 issuer以及是否在有效期内。工具列表为空tools/list 返回空数组说明 OpenAPI 注解没有生效。检查三点x-google-api-management.mcp.enabled是否设为trueoperation 是否有x-google-mcp-tool注解OpenAPI 版本是否为 3.0.x 或 3.1.x。OpenAPI 2.0 不支持 MCP 注解。tools/call 返回参数映射错误如果 tools/call 报参数错误检查x-google-mcp-tool的 name 是否与请求中的 name 一致以及 arguments 的字段名是否与 OpenAPI schema 中的参数名匹配。路径参数、query 参数和 body 参数的映射规则不同路径参数需要在 arguments 中提供对应的 key。CC Switch / Cline MCP / Codex auth.json 配置如果你用 CC Switch 或 Cline 的 MCP 功能接入需要写全三件套Base URL、Key、Model ID。Base URL 填https://taotoken.net/apiKey 填 TaoToken 控制台获取的 KeyModel ID 填你实际使用的模型标识。Codex 的auth.json配置类似确保这三个字段完整缺一个都会导致连接失败。排查时建议按“先原接口、再 MCP 协议、最后 Agent 客户端”的顺序不要一上来就怀疑最外层。大部分问题出在鉴权 header 和 OpenAPI 注解上。6. 语义一致 CTA把工具调用闭环跑起来配置和验证都通过后最后一步是把这套 MCP 工具接入你的实际 Agent 工作流。TaoToken 在这里提供的是统一 Key 和 API 通道让你不需要为每个模型或每个客户端单独管理凭证。如果你主要做排障和接入先去 API Keys 页面https://taotoken.net/console/api-keys确认 Key 状态然后对照接入文档https://taotoken.net/doc检查配置。文档里有完整的 Base URL、Key 和 Model ID 说明。如果你要验证模型是否能正确选择工具用模型对话https://taotoken.net/model-chat直接测试。把 MCP 端点配置进去让模型实际调用get_order_status观察它是否根据 description 正确判断了调用时机。如果你在做长期编码或 Agent 项目Coding Planhttps://taotoken.net/coding-plan提供更稳定的调用配额。对于 Claude Code 用户ClaudeCodeAnthropic 接入页https://taotoken.net/claude-code-anthropic有专门的配置说明。回到 Google Cloud API Gateway 原生 MCP 这件事它的长期价值不在于“少写一个 MCP Server”而在于让 REST 客户端和 Agent 最终回到同一条生产治理链。以后接口权限调整、配额修改或后端迁移时不需要同步维护第二套 MCP 中间层系统里也少了一条可能慢慢漂移的备用路径。落地时按四步走先挑 3 到 5 个只读或低风险 operation给每个 operation 写清楚x-google-mcp-tool的 name 和 description用 tools/list 检查模型看到的 schema再用 tools/call 跑一遍原鉴权、配额和日志链路。四步都对上再扩大工具数量。工具目录不是越丰富越好。如果几十个工具里真正高频的只有十几个减少暴露面会让模型选择更稳定也让权限审查和回归测试的成本下降。先把高价值工具跑稳比一次把几百个内部接口全部暴露更容易治理。