Google 把 REST 收進 API Gateway 的 MCP 之後，發現面為什麼還是 JSON？從 OpenAPI 3.x 到 tools/list

先給結論：Gateway 替你當了 MCP Server，發現合約仍是一份 JSON。2026 年 9 月 24 日，Google 開發者部落格宣佈：Cloud API Gateway 進入 Public Preview，可以把已部署的 OpenAPI 3.x 操作暴露成遠端 MCP 工具，不必再自建、自託管一層 MCP Server。文件側更早：9 月 11 日的 release notes 已經寫上 Enable MCP。閘道器在 /mcp 收標準 JSON-RPC，把 tools/call 轉成原來的 REST，JWT、API Key、配額、日誌走同一條策略。Agent 看見的不是「REST 變魔法」，而是 tools/list 吐出來的工具名和 input schema——還是 JSON。

這篇按 2026 年 9 月 30 日寫，依據當天仍有效的開發者博文與 API Gateway 文件。本站已有《MCP 是什麼》《Skill 上了 MCP，發現文件為什麼還是 JSON》《惡意 JSON 與 Tool Calling》。本文只回答：OpenAPI 收進閘道器之後，哪一層 JSON 要先核，哪一層預設裸奔。

閘道器當 MCP Server，發了什麼

官方說法很短：企業能力大多在 REST 後面，Agent 看不見。以前要給 Agent 呼叫，團隊通常再立一個 MCP Server，把路由、鑑權、配額再實現一遍。API Gateway 是 Google Cloud 閘道器產品線裡偏輕的入口；Cloud Run 上的服務要在幾分鐘內管起來並暴露給 Agent，走這條。完整生命週期、複雜流量、變現走 Apigee。管 Agent 往外打的呼叫（含這類 MCP Server）走 Agent Gateway。出站模型路由是另一方向，和 MCP 不能寫在同一份 API config。

支援的生命週期方法只有四條：initialize、notifications/initialized、tools/list、tools/call。其它方法（resources/*、prompts/*）回 JSON-RPC -32601。傳輸是 HTTP POST，沒有 stdio。協議頭示例寫的是 MCP-Protocol-Version: 2025-11-25。規範本身在 2026-07-28 已經改過握手，閘道器預覽釘的是 2025-11-25——連版本號都是 JSON 信封裡要先對齊的欄位。

這不是再寫一個 MCP Server

轉碼後的 REST 請求和瀏覽器、SDK 打進來的請求走同一條策略。配額按操作計，MCP 和 REST 共用額度。後端不用為 Agent 再開一套介面。變的是發現面：以前人讀 OpenAPI；現在模型讀 tools/list 裡的 JSON Schema。

所以「不用維護 MCP Server」不等於「不用維護 JSON 合約」。OpenAPI 裡空描述、過深的物件、2.0 殘留，都會在發現面或轉碼時露出來。原理見《MCP 是什麼》。

合約從 OpenAPI 3.x 長出來

文件級開啟 MCP：x-google-api-management.mcp。單個操作可用 x-google-mcp-tool 改名、改描述，或設 false 退出。每個要暴露的操作需要後端，以及非空 description。只收 GET / POST / PUT / PATCH / DELETE。工具名須匹配 [A-Za-z0-9_.-]{1,128}，全閘道器唯一。

官方示例的最小形狀（YAML 寫，語義是 JSON 物件）：

x-google-api-management:
  mcp: true
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order."
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string

描述是模型決定「何時該調」的主訊號。官方要求寫 when / why，不要只寫返回了什麼。路徑、查詢、body、頭上的 schema，會對映成工具 arguments。巢狀物件在 tools/list 裡可能展不全——這是預覽期寫明的限制，不是你的校驗器壞了。先在本機把 OpenAPI 攤平，再和閘道器吐出的 input schema 做 Diff。

tools/list 預設不鑑權

預設誰都能 POST /mcp 要一份工具清單：名字、描述、input schema。開發方便，生產等於把參數合約公開。官方建議給 tools/list 上 JWT。Public Preview 裡API Key 保不了這個方法。寫成物件形式也會全域性開啟 MCP；不想全暴露的操作，必須 x-google-mcp-tool: false。

x-google-api-management:
  mcp:
    tools-list:
      security:
        orderServiceJwt: []

tools/call 始終執行底層 REST 的鑑權，和發現面是否上鎖無關。清單裸奔、呼叫上鎖，是兩回事。把工具名和 schema 當機密的團隊，上線前先鎖 tools/list。這和《惡意 JSON 指南》同一層：模型看見的合約越寬，注入面越大。

tools/call 仍是 JSON-RPC

線上形狀官方寫成：

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}

閘道器把 arguments 填回 path / query / body / header，過策略，再把後端響應包成 MCP result。除錯時先分清兩層：外層是 JSON-RPC 信封，內層是業務 JSON。哪一層 parse 失敗，先看哪一層。ADK 示例用 Streamable HTTP 指到 …/mcp，請求頭仍可帶閘道器已有的憑據。

接入 API hub 後，開了 MCP 的閘道器會帶 MCP 後設資料出現，並進 Agent Registry。發現目錄變了，欄位合約沒有變：還是你那份 OpenAPI 長出來的 schema。Skill 發現那條線見《SEP-2640 與 skill://index.json》——索引是另一份 JSON，不要和 tools/list 混成一張表。

Public Preview 先看清的限制

• OpenAPI 2.0 不支援，先升 3.x。
• 空響應體（如 HTTP 204）的操作不會暴露成工具。
• 過深的物件 schema，tools/list 可能截斷。
• 單個閘道器最多約 1000 個工具。
• 同一份 API config 不能同時開 MCP 和 model routing。
• resources / prompts、響應流、Model Armor 檢查還在路線圖上。

這些不是「以後再補的體驗問題」。204 介面從清單裡消失，模型會改調別的工具。schema 被截斷，strict 校驗和真實後端會對不上。本站《MCP 2026 遷移指南》講的是協議版本；這篇多出來的是：閘道器替你生成的那份 list，未必等於你倉庫裡的完整 OpenAPI。

上線前先核的四份 JSON

1. 倉庫裡的 OpenAPI 3.x。2.0 先升。每個要暴露的操作有非空 description、後端、合法 tool 名。
2. 閘道器返回的 tools/list。對照 input schema 是否被截斷、是否多出不想公開的操作。
3. 一條真實的 tools/call。arguments 是否填得回 REST；外層 jsonrpc 是否 2.0。
4. 發現面的安全物件。生產不要讓 tools/list 繼續裸奔。JWT 方案名必須是 components.securitySchemes 裡已有的那一個。

用本機 JSON 工具看規格

開啟 MCP 開關之前，在瀏覽器裡攤開三份文字：OpenAPI（YAML 先轉 JSON）、一次 tools/list 響應、一條準備發給 tools/call 的 arguments。

• JSON 校驗 — 文法是否合法；有 Schema 就一起核必填和多餘鍵。
• JSON ↔ YAML — 多數 OpenAPI 以 YAML 入庫，先轉成 JSON 再和 list 對比。
• JSON Diff — 對比「倉庫裡的 parameters schema」和「閘道器吐出的 inputSchema」。

資料不離開瀏覽器。合約看平了，再改閘道器開關。Gateway 會替你轉碼；你的欄位名和 required 不應跟著預覽期的截斷一起鬆。

常見問題 FAQ

總結

API Gateway 收走的是 MCP Server 程式，不是 JSON 合約。OpenAPI 3.x 長出 tools/list，tools/call 仍是 JSON-RPC，策略仍是原來的 REST。預設不鑑權的清單、被截斷的巢狀 schema、204 介面消失，都是上線前的核對項，不是「開了預覽就完事」。

先在本機把 OpenAPI、list 響應、call 樣本看平，再開啟 mcp: true。閘道器會替你轉碼；欄位合約不應跟著預覽限制一起鬆。