Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定 Model Context Protocol

本文說明如何設定 API Gateway，使其做為遠端 Model Context Protocol (MCP) 伺服器。

事前準備

請確認 API 具有有效的 OpenAPI 3.x 規格。OpenAPI 2.0 不支援 MCP。
請務必瞭解 API Gateway 的基本概念。

設定驗證

上傳 OpenAPI 規格時，API Gateway 會對 MCP 設定執行下列驗證：

位置：x-google-mcp-tool 擴充功能只能在個別作業層級指定。
HTTP 方法：只有 GET、POST、PUT、PATCH 和 DELETE 作業可以公開為 MCP 工具。
工具名稱：工具名稱必須與 [A-Za-z0-9_.-]{1,128} 相符，且在規格中不得重複。
說明：每個工具都必須解析為非空白說明 (取自作業的說明、摘要或覆寫)。如果作業沒有可解決的說明，系統會拒絕。
安全性：如果為 tools/list 設定驗證，您必須為 components.securitySchemes 下定義的 JWT 安全性架構命名。公開測試版不支援 tools/list 的 API 金鑰安全性。

驗證模型

API Gateway 會根據呼叫的 MCP 方法套用不同的驗證規則：

通訊協定生命週期：initialize 和 notifications/initialized 方法為未經驗證。
工具叫用 (tools/call)：重複使用在 OpenAPI 規格中為基礎作業定義的驗證政策。與直接呼叫 REST 端點一樣，這項功能也會強制執行相同的 API 金鑰或 JWT 規定。
工具探索 (tools/list)：預設情況下，這個方法未經過驗證。不過，為確保安全性，強烈建議您使用 tools-list.security 為這個方法啟用驗證，保護工具探索程序。如果您選擇啟用驗證，請務必使用 JWT 安全性配置。tools/list 不支援 API 金鑰驗證。

設定 MCP 的步驟

請按照下列步驟將 API 公告為 MCP 工具：

1. 找出要公開的作業

查看 OpenAPI 規格，並決定 AI 代理應可執行的作業。

2. 更新 OpenAPI 規格

您可以為所有符合資格的作業全域啟用 MCP，也可以針對個別作業進行設定。

全球啟用

如要全域啟用 MCP，請在文件層級將 mcp 欄位新增至 x-google-api-management：

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

全域啟用後，所有符合資格的作業 (根據 HTTP 方法和路徑) 都會顯示為 MCP 工具。根據預設，工具名稱是作業的 operationId，說明則是作業的說明或摘要。

每個作業的設定

您可以使用 x-google-mcp-tool 覆寫全域設定，或選擇性公開作業：

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

如果全域啟用作業，您也可以設定 x-google-mcp-tool: false 來選擇停用作業。

3. 驗證 `tools/list` (建議)

根據預設，tools/list 方法 (會列舉可用工具) 未經過驗證。為確保安全，強烈建議您在 x-google-api-management/mcp 下方設定 tools-list.security，強制執行驗證。您必須使用 JWT 結構，這個方法不支援 API 金鑰。

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

4. 建立及部署 API 設定

從註解規格建立 API 設定，並使用標準流程部署至閘道。詳情請參閱「將 API 部署至閘道」。

5. 驗證 MCP 支援

部署完成後，您可以驗證閘道是否正在處理 MCP 要求。

握手

傳送初始化要求，建立通訊協定版本和功能：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

確認握手

確認初始化。閘道會以 HTTP 202 Accepted 回應：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

探索工具

列出可用的工具：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

引數如何對應至 REST 要求

系統會根據 OpenAPI 規格，將傳遞至工具的引數對應至基礎 REST 要求：

路徑和查詢參數：成為 arguments 物件中的頂層屬性，並以 OpenAPI 參數名稱做為鍵。
要求主體：內嵌於名為 body 的單一屬性下。舉例來說，如要建立資源，請傳遞 {"body": {"fieldName": "value"}}。
標題：也會成為頂層屬性。閘道會在後端呼叫中，將這些標頭插入為標準 HTTP 標頭。

轉碼後的後端要求與直接向後端服務發出的 REST 要求並無不同。後端服務無法以程式輔助方式區分直接 REST 呼叫和從 MCP 轉碼的呼叫。

叫用工具

叫用特定工具。如果底層 REST 作業需要驗證權杖，請務必加入：

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

觀測能力

MCP 要求會產生標準 API Gateway 指標和記錄。您可以檢查要求路徑 (通常以 /mcp 結尾) 或設定自訂指標，區分 MCP 流量與標準 REST 流量。

排解 MCP 失敗問題

MCP 會區分傳輸失敗和通訊協定失敗。對於通訊協定和應用程式錯誤，閘道會傳回 HTTP 200 和 JSON-RPC 錯誤物件，因為非 200 回應可能會導致許多 MCP 用戶端在傳輸層失敗。

下表說明常見徵兆和修正方式：

問題	JSON-RPC 程式碼	HTTP 狀態	意義和常見修正方式
不允許的方法	不適用	`405`	非 POST 要求已送達 `/mcp`。僅支援 HTTP `POST`。
JSON 剖析錯誤	`-32700`	`400`	要求主體不是有效的 JSON。
方法或 ID 遺失/無效	`-32600`	`200`	內文是有效的 JSON，但不是有效的 JSON-RPC 要求。檢查必填欄位 (`jsonrpc`、`method`、`id`)。
不支援這個方法	`-32601`	`200`	方法超出支援範圍 (例如 `ping`)。
不支援的通訊協定版本	`-32602`	`200`	`protocolVersion` 指定的版本不支援閘道。
缺少通訊協定版本	`-32602`	`200`	`initialize` 參數省略 `protocolVersion`，或不是字串。
不明工具	`-32602`	`200`	找不到工具名稱。清除用戶端快取或驗證部署作業。
工具引數無效	`-32602`	`200`	缺少引數或引數無效。驗證 `body` 金鑰巢狀結構。
內容過多	`-32000`	`200`	回應酬載超過大小限制。
傳輸主體過大	不適用	`413`	原始 HTTP 要求主體超過閘道傳輸限制。
伺服器錯誤	`-32000`	`200`	無法剖析後端回覆。檢查記錄。
未授權 / 禁止	不適用	`401`/`403`	驗證失敗。回應會攜帶 `WWW-Authenticate` 標頭，指向受保護的資源中繼資料。

後端應用程式錯誤通常會以成功的 JSON-RPC 回應 (HTTP 200) 形式呈現，其中 result.isError: true 包含後端錯誤主體。