排解 Apigee 中的 MCP 部署問題

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明如何排解及解決 MCP 探索 Proxy 部署作業的問題。您可以在這個頁面瞭解 MCP 部署作業的非同步佈建生命週期、解決錯誤代碼，以及驗證執行階段連線。

瞭解 MCP 部署作業

部署 MCP Discovery Proxy 是非同步的多步驟程序，可確保設定在 Proxy 部署完成前，完全傳播至 Apigee 和 Google Cloud 基礎架構。

在執行這些下游佈建步驟時，UI 會顯示 Proxy 處於「佈建」狀態。 程序完成後，狀態會變更為「已部署」。這個狀態表示所有下游元件都已完整佈建，且 Proxy 已準備好處理流量。

疑難排解

以下各節說明您在 Apigee 中使用 MCP 時可能會遇到的錯誤和已知問題。

工具呼叫和中繼資料的錯誤回應狀態碼

Apigee MCP 端點會傳回 HTTP 狀態碼，這些狀態碼遵循Model Context Protocol (MCP) 規格和相關 OAuth 標準。瞭解這項行為有助於您在 MCP 用戶端或 AI 代理程式中正確處理錯誤。

下表列出 Apigee MCP 端點傳回的狀態碼：

範例：工具執行錯誤回應內容

工具呼叫失敗時，Apigee MCP 會傳回 HTTP 200 OK，並在 JSON-RPC result 物件中回報失敗情形，且 isError 會設為 true。後端傳回的原始錯誤會保留：後端回應內文會逐字 (以字串形式) 放在 result.content[].text 中。舉例來說，如果後端傳回 HTTP 404，且內文為 {"error":"User 42 not found"}，則 MCP 回應如下：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

id 與 tools/call 要求中的 id 相符。 如果後端未傳回任何回應主體，text 會改為包含產生的摘要，例如 Operation failed (HTTP 500).

MCP 用戶端應檢查 result.isError (而非 HTTP 狀態碼)，偵測工具呼叫是否失敗。如果用戶端程式碼特別預期 4xx 或 5xx HTTP 狀態會發出工具執行錯誤信號，則這項變更生效後，系統將不再偵測到錯誤，因為回應現在是 HTTP 200 OK。更新這類用戶端，以便讀取 result.isError 和 content 陣列。

通訊協定層級的錯誤 (例如格式錯誤的 JSON-RPC 要求) 與工具執行錯誤不同，這類錯誤會繼續在 JSON-RPC error 物件 (例如 {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) 中傳回，而不是在 result.isError 中傳回。

建議：符合標準的 MCP 用戶端會透過預設邏輯處理這些狀態碼，因此不需要進行任何變更。如果您先前已新增用戶端解決方法來處理非標準狀態碼 (例如剖析 tools/call 錯誤的非 2xx 回應主體，或將 PRM 端點的 500 回應視為「未設定中繼資料」)，建議您移除該解決方法。否則，用戶端可能會繼續使用過時的處理邏輯，而不是正常處理修正後的狀態碼。

瀏覽器型 MCP 呼叫的 CORS 政策

如果直接從瀏覽器發出 Apigee MCP 呼叫 (例如 MCP 檢查器使用「Direct」設定，而非「Via Proxy」)，就必須採用跨源資源共享 (CORS) 政策。根據預設，MCP Discovery Proxy 範本會在 Proxy 套件的 Proxy 端點「要求 PreFlow」中加入 Apigee CORS 政策，以啟用瀏覽器型呼叫。

如果直接從瀏覽器呼叫時發生 CORS 相關問題，您可能需要在 MCP Discovery Proxy 組合的 Proxy 端點 Request PreFlow 中調整 CORS 政策設定。

將要求傳送至 MCP 端點時發生 JSON 剖析錯誤

當您將要求傳送至 MCP 端點時，可能會收到類似下列的錯誤訊息 (或具有不同的錯誤代碼和訊息)：

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

在這種情況下，建議您確認下列資訊：

• 您已輸入正確的 MCP 端點網址。
• 您的要求格式正確。
• 您存取的是支援的方法。
• 您已在 支援的區域啟用及設定 MCP Discovery Proxy。如需可能設有容量限制的地區清單，請參閱部署失敗。

部署失敗

如果 MCP Discovery Proxy 部署失敗，且 UI 中顯示「失敗」狀態，請查看錯誤訊息瞭解詳情。常見的失敗原因包括：

• 網路設定失敗或 OAS 中有不支援的結構定義：這些錯誤通常表示 OpenAPI 規格有問題。確認規格有效，且使用支援的版本。
• 區域容量限制：如果看到負載平衡器佈建失敗相關錯誤，或佈建狀態一直未變更為「已部署」，可能是因為下列其中一個區域的基礎架構容量暫時達到上限：
  • asia-east2
  • asia-northeast3
  • asia-southeast2
  • australia-southeast1
  • europe-central2
  • europe-west12
  • europe-west9
  • me-central2
  • us-central2

  如要解決這個錯誤，請嘗試將 Proxy 部署到其他區域的環境。

無法在 API 中心將 API 樣式變更為 MCP

如果 Apigee API 中心已存在具有現有 API 作業的 API 資源，您就無法將該資源的「API 樣式」屬性變更為「MCP」。如要向 Apigee API 中心註冊 API 做為 MCP API，您必須在首次註冊 API 時選取 MCP 樣式，或確保 API 資源上沒有任何作業，再將樣式變更為 MCP。

如果遇到其他問題，請參閱「使用偵錯」，詳細瞭解如何在 Google Cloud 控制台中使用偵錯工具，分析 MCP Discovery Proxy 的要求和回應。