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 配置或 API 金鑰配置。如果使用 JWT 配置，也必須在規格的頂層 security 需求中命名。

驗證模型

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

通訊協定生命週期：initialize 和 notifications/initialized 方法未經驗證。
工具叫用 (tools/call)：重複使用 OpenAPI 規格中基礎作業定義的驗證政策。這項功能會強制執行與直接呼叫 REST 端點相同的 API 金鑰或 JWT 規定。
工具探索 (tools/list)：根據預設，這個方法未經驗證。不過，為確保安全性，強烈建議您使用 tools-list.security 啟用這個方法的驗證機制，保護工具探索功能。您可以使用 JWT 或 API 金鑰驗證 tools/list。

設定 MCP 的步驟

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

1. 找出要公開的作業

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

2. 更新 OpenAPI 規格

您可以全域啟用 MCP，套用至所有符合條件的操作，也可以針對個別操作進行設定。

全球啟用

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

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 金鑰配置。

以下範例需要 JWT：

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

以下範例需要 API 金鑰。用戶端必須在 x-api-key HTTP 標頭中傳送金鑰；tools/list 不會從查詢參數讀取 API 金鑰。如果要求未提供有效金鑰，就會收到 JSON-RPC 錯誤，且不會傳回工具清單。如要瞭解如何建立 API 金鑰，請參閱「使用 API 金鑰」。

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. 建立及部署 API 設定

使用標準流程，根據加上註解的規格建立 API 設定，並部署至閘道。詳情請參閱「將 API 部署至閘道」。如要日後變更工具，請參閱「更新公開的 MCP 工具」。

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"}'

探索工具

列出可用的工具。如果您設定了 tools-list.security，請新增相符的憑證，例如 JWT 的 Authorization: Bearer 標頭或 API 金鑰的 x-api-key 標頭：

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 中的 API 設定不可變更，因此您無法變更現有 API 設定中的 API 定義。因此，每個已部署的 API 設定都會傳回靜態 tools/list 回應。

如要新增、移除、重新命名或更新公開的 MCP 工具或 tools/list 安全性設定，請建立新的 API 設定並部署至閘道：

更新 OpenAPI 3.x 規格，包括作業、operationId 值、摘要、參數，以及 x-google-api-management.mcp 和 x-google-mcp-tool 擴充功能。
使用新的 API 設定 ID 建立新的 API 設定：
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
更改下列內容：
- NEW_CONFIG_ID：更新後 API 設定的新 ID
- API_ID：API Gateway API 的 ID
- API_DEFINITION：更新後的 OpenAPI 3.x 規格路徑
- PROJECT_ID：您的 Google Cloud 專案 ID
- SERVICE_ACCOUNT_EMAIL：服務帳戶的電子郵件地址，用於為已設定驗證機制的後端簽署權杖。如果後端都不需要驗證，請省略這個旗標。
詳情請參閱「建立 API 設定」。
更新提供 API 的各個閘道，改用新的 API 設定：
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
更改下列內容：
- GATEWAY_ID：要更新的閘道 ID
- GCP_REGION：閘道部署所在的區域
詳情請參閱「更新閘道」。
呼叫 tools/list 即可查看更新後的工具組合。如需要求範例，請參閱「探索工具」。
確認沒有任何閘道使用舊版 API 設定後，請刪除該設定：
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
將 OLD_CONFIG_ID 替換為已取代的 API 設定 ID。請勿在任何閘道仍使用 API 設定時刪除該設定；如果新的 API 設定重新命名或移除配額指標，仍提供舊版 API 設定的閘道可能會傳回 HTTP 500 錯誤，直到更新為止 (請參閱「配額適用於整個 API」)。詳情請參閱「刪除 API 設定」。

更新 MCP 工具時，請留意下列推出和用戶端行為：

不必停機即可推出：API Gateway 更新閘道時不必停機。新的 API 設定傳播期間，部分要求可能會短暫傳送至先前的 API 設定。如果 API 部署在多個閘道或區域，請分別更新每個閘道。
用戶端工具快取：API Gateway 透過無狀態 HTTP 傳輸提供 MCP，因此不會發出 notifications/tools/list_changed 通知。閘道更新完成後，快取工具定義的 MCP 用戶端必須再次呼叫 tools/list，才能找到更新後的工具。
API 設定限制：每個 API 最多只能有 100 項 API 設定，因此請在更新閘道後刪除已取代的 API 設定。請一次建立一項 API 設定。如果為同一個 API 啟動第二項 API 設定時，第一項設定尚未完成，則閘道可能無法使用其中一項或兩項設定。詳情請參閱「配額與限制」。

觀測能力

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 或方法/ID 無效	`-32600`	`200`	內文是有效的 JSON，但不是有效的 JSON-RPC 要求。檢查必填欄位 (`jsonrpc`、`method`、`id`)。
不支援這個方法	`-32601`	`200`	方法超出支援範圍 (例如 `ping`)。
不支援的通訊協定版本	`-32602`	`200`	`protocolVersion` 指定了閘道不支援的版本。
缺少通訊協定版本	`-32602`	`200`	`initialize` 參數省略 `protocolVersion`，或該參數不是字串。
不明工具	`-32602`	`200`	在已部署的 API 設定中找不到工具名稱。請重新整理用戶端工具快取，或參閱「更新公開的 MCP 工具」。
工具引數無效	`-32602`	`200`	缺少引數或引數無效。請確認 `body` 鍵巢狀結構。
內文過大	`-32000`	`200`	回應酬載超過大小上限。
傳輸主體過大	不適用	`413`	原始 HTTP 要求主體超過閘道傳輸限制。
伺服器錯誤	`-32000`	`200`	無法剖析後端回應。查看記錄。
未經授權/禁止	不適用	`401`/`403`	驗證失敗。回應會包含指向受保護資源中繼資料的 `WWW-Authenticate` 標頭。

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