排解 Apigee 中的 MCP 部署問題

本頁面適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

瞭解 MCP 部署作業

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

在這些下游佈建步驟進行期間,UI 會顯示 Proxy 處於「Provisioning」(佈建中) 狀態。程序完成後,狀態會變更為「已部署」。這個狀態確認所有下游元件都已完整佈建,且 Proxy 已準備好處理流量。

疑難排解

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

問題:後端從一個要求位置 (查詢字串、標頭或 Cookie) 讀取工具引數,但 OpenAPI 規格宣告參數 in 位於不同位置,因此引數會抵達後端要求的其他位置。呼叫會失敗,或行為就像沒有引數一樣。

症狀:tools/call 要求在 MCP 層成功,且 MCP 用戶端提供引數,但後端回應時卻像缺少值一樣,例如必要值出現 400,或套用預設值而非傳送的值。

原因:參數在 OpenAPI 規格中宣告為 in: header 或 in: cookie,因此 Apigee 會將其值做為要求標頭或在 Cookie 標頭中傳送,而不是在查詢字串中傳送。如果後端只從查詢字串讀取值,就不會看到該值。請參閱「後端要求中的工具引數位置」。

解決方法:決定值所屬的位置,並確保規格和後端一致:

  • 如要保留查詢字串中的值,請宣告 in: query 參數。
  • 如要以標頭或 Cookie 的形式傳送,請保留宣告,並從後端的位置讀取值。

問題:MCP 用戶端發出的 HTTP 要求中包含 Cookie (例如瀏覽器用戶端的工作階段 Cookie),但某些工具呼叫無法將 Cookie 傳送至後端。

症狀:後端行為就像呼叫端未通過驗證或未在工作階段中,且行為不一致:相同作業在某些呼叫中有效,在其他呼叫中則無效。

原因:作業宣告一或多個 in: cookie 參數,且受影響的呼叫提供至少一個參數。Cookie 標頭會整體重寫,而非附加,因此在這些呼叫中,標頭只會攜帶宣告的 Cookie 參數,其他 Cookie 則會捨棄。未提供任何 Cookie 參數的呼叫會直接傳遞標頭,因此只有部分呼叫會失敗。請參閱「傳送至後端的要求中的 Cookie」。

解決方法:在需要後端 Cookie 的每個作業中,將這些 Cookie 宣告為 in: cookie 參數,這樣工具呼叫就會一律提供 Cookie 值,而非沿用用戶端要求的值。沒有任何設定可以保留未宣告的 Cookie。

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

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

下表匯總 Apigee MCP 端點傳回的狀態碼:

情境 HTTP 狀態碼 回應主體
工具在 tools/call 執行失敗 (例如後端 API 傳回 4xx 或 5xx 錯誤,例如驗證錯誤或缺少必填欄位)。 200 OK CallToolResult,其中 result.isError 設為 true,錯誤詳細資料則位於 content。這樣一來,MCP 用戶端和 LLM 代理就能讀取錯誤並復原 (例如重新提示輸入缺少的內容並重試),而不是終止工作階段。
未設定受 OAuth 保護的資源中繼資料 (PRM),或在 /.well-known/oauth-protected-resource/mcp 找不到。 404 Not Found 表示要求的位置沒有受保護的資源中繼資料。
缺少存取權杖,或權杖無效/過期。 401 Unauthorized 包含 WWW-Authenticate 驗證,可驅動 OAuth 探索流程。
存取權杖範圍不足。 403 Forbidden 包含 WWW-Authenticate 驗證,可驅動逐步授權流程。

範例:工具執行錯誤回應主體

工具呼叫失敗時,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 用戶端會透過預設邏輯處理這些狀態碼,因此不需進行任何變更。如果您先前曾新增用戶端解決方法來處理非標準狀態碼,例如剖析非 2xx 回應主體來找出 tools/call 錯誤,或將 PRM 端點的 500 回應視為「未設定中繼資料」,建議您移除該解決方法。否則,用戶端可能會繼續使用過時的處理邏輯,而不是正常處理更正後的狀態碼。

瀏覽器 MCP 呼叫的 CORS 政策

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

如果直接從瀏覽器發出呼叫時遇到 CORS 相關問題,可能需要調整 MCP 探索 Proxy 套件中,Proxy 端點要求 PreFlow 的 CORS 政策設定。

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

向 MCP 端點傳送要求時,您可能會收到類似下列的錯誤訊息 (或不同的錯誤代碼和訊息):

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

在這種情況下,建議您確認下列資訊:

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

部署失敗

如果 MCP Discovery Proxy 部署失敗,且使用者介面顯示「Failed」(失敗) 狀態,請查看錯誤訊息,瞭解詳細資訊。常見的失敗原因包括:

  • Networking configuration failed 或 Unsupported Schema in OAS:這些錯誤通常表示 OpenAPI 規格有問題。請確認規格有效,且使用支援的版本。
  • 區域容量限制 (僅限 Apigee):如果看到與負載平衡器佈建失敗相關的錯誤,或佈建狀態一直未變更為「已部署」,可能是下列其中一個區域的基礎架構容量暫時受限:
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    如要解決錯誤,請嘗試將 Proxy 部署至其他區域的環境。這種失敗模式不適用於 Apigee Hybrid,因為執行階段基礎架構是您自己的叢集。

  • 叢集未啟用 MCP (僅限 Apigee hybrid):如果 MCP Proxy 部署作業無限期停留在「佈建中」狀態,且從未達到「已部署」狀態,請確認叢集是否已啟用 MCP。請參閱下方的「叢集端診斷」。

叢集端診斷 (僅限 Apigee hybrid)

Apigee hybrid MCP 資料層會在您自己的 Kubernetes 叢集內執行,因此叢集內故障模式會透過對叢集執行 kubectl 來診斷。請依序完成下列診斷檢查清單。

步驟 1:確認叢集已啟用 MCP

MCP 會部署為 ApigeeDeployment 自訂資源 (由 Apigee 運算子管理),而非一般的 Kubernetes Deployment。檢查 MCP ApigeeDeployment:

kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server

預期輸出內容 (資源名稱包含衍生自組織的後置字串,此處顯示為 ORG_CR_SUFFIX):

NAME                                     STATE     NESTEDSTATE   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX       running                 1h

如果指令傳回 No resources found in APIGEE_NAMESPACE namespace.,表示 MCP 未啟用。返回「在 Apigee hybrid 中啟用 MCP」,確認 enableMcpServer: true 已設為 overrides.yaml 中的頂層金鑰,且您已在 apigee-org 版本之前升級 apigee-operator Helm 版本。請參閱啟用程序中的步驟 3 和步驟 4,瞭解正確的 helm 指令。

步驟 2:確認 MCP Pod 正在執行

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server

預期輸出內容 (Pod 後置字串會不同):

NAME                                                              READY   STATUS    RESTARTS   AGE
apigee-mcp-server-default-ORG_CR_SUFFIX-1170-abcd1234   2/2     Running   0          1h
apigee-mcp-server-default-ORG_CR_SUFFIX-1170-efgh5678   2/2     Running   0          1h

Pod 名稱會遵循 apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH 範本,其中 REV 是四位數的混合版本修訂版本 (例如混合 1.17.0 的 1170),POD_HASH 則是八個英數字元組成的後置字串,每個 Pod 的後置字串都不同。

每個 Pod 都必須在 READY 欄中顯示 2/2,並在 STATUS 欄中顯示 Running。如果 Pod 不是 Running,kubectl -n APIGEE_NAMESPACE describe pod POD_NAME 會顯示原因。常見原因包括映像檔提取失敗 (請確認從叢集到 overrides.yaml 中設定的映像檔登錄檔的輸出),以及 CPU 或記憶體空間不足 (請提高 overrides.yaml 中的 mcpServer.resources.requests)。

步驟 3:檢查 Sidecar 設定提取狀態

每個 MCP Pod 中的 apigee-mcp-server-config 邊車容器會定期從 Apigee 控制層提取 MCP 設定。每次提取時,系統都會從 apigee.googleapis.com 擷取目前的設定參照,然後從 Cloud Storage 擷取參照的設定套件。提取作業成功完成並取得有效設定後,MCP 資料層就會開始在 https://mcp.apigee.internal/mcp 上提供 MCP 工具流量。

在首次成功提取有效設定之前 (可能是因為尚未為貴組織部署 MCP Discovery Proxy,或 Sidecar 無法連線至控制層),MCP Pod 會維持 Ready 狀態,但對 https://mcp.apigee.internal/mcp 的要求會失敗,並顯示「連線遭拒」。

檢查 sidecar 記錄,判斷您屬於哪種情況:

kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
  • 重複的 info 行,表示控制層沒有 MCP 設定:
    {"level":"info","ts":1787582542.68,"caller":"mcpsidecar/sidecar.go:397","msg":"mcpsidecar: no MCP config from CP yet; skipping tick, pod stays Ready via seed","org":"YOUR_ORG","mcp_server_id":"default"}
    Apigee 控制層傳回成功回應,但貴組織尚未部署 MCP Discovery Proxy。這是新手上路期間的預期穩定狀態。如要將 MCP 資料層轉換為服務狀態,請按照 MCP 快速入門導覽課程部署 MCP Discovery Proxy。
  • error 行,包含 consecutive_failures 計數器:
    {"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}
    Sidecar 記錄是結構化 JSON。如果看到 "level":"error" 且 consecutive_failures 計數器上升,表示 Sidecar 無法完成設定提取。sidecar 會自動重試並退避,並在下次成功提取時將計數器重設為 0。

    如果這個計數器持續上升,請檢查下列常見根本原因:

    • apigee-watcher Google Cloud 服務帳戶不在 Apigee 組織 controlPlaneAccess 資源的 watcher_identities 清單中。請參閱啟用程序中的「步驟 2:將控制層 MCP 設定的存取權授予監控程式身分」,瞭解如何新增授權並確認授權已生效。
    • 從叢集輸出至 apigee.googleapis.com 或 storage.googleapis.com 的流量會遭到封鎖。兩個端點都必須可從 MCP Pod 連線 (請參閱啟用程序中的傳出網路需求)。
    • apigee-watcher 服務帳戶無法從這個叢集取得 Google Cloud 存取權杖。如果相同命名空間中的現有 Apigee hybrid 元件也回報驗證失敗,請先解決共用驗證問題。
    • 暫時性的 Apigee 控制層或 Cloud Storage 錯誤。如果排除上述原因後,計數器仍持續上升一段時間,請與 Apigee 支援團隊聯絡。

步驟 4:確認已插入訊息處理器 hostAliases

啟用 MCP 時,Apigee 運算子會將一個 hostAliases 項目插入訊息處理器 (MP) Pod 規格。該項目包含一個 IP (MCP 服務 ClusterIP) 和兩個主機名稱:mcp.apigee.internal 和小寫的 ORG_NAME.mcp.apigee.internal。確認注入成功:

kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-runtime \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'

每個列出的 MP Pod 都必須有 hostAliases 項目,其中包含 mcp.apigee.internal 和小寫 ORG_NAME.mcp.apigee.internal,指向 MCP Service ClusterIP。如果 MP Pod 顯示空白或缺少項目,表示該 Pod 是在啟用 MCP 之前建立。刪除受影響的 MP Pod,讓 ApigeeDeployment 控制器根據目前的 Pod 規格 (包括插入的 hostAliases 項目) 重新建立 Pod:

kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime

步驟 5:端對端驗證

如要進行端對端測試,透過 MCP 資料層傳送實際的 MCP initialize 要求,請部署 MCP Discovery Proxy,並按照 MCP 快速入門導覽課程操作。在為貴組織部署 MCP 探索 Proxy 之前,無論訊息處理器是否能連線至 MCP Pod,傳送至 https://mcp.apigee.internal/mcp 的要求都會失敗,並顯示「連線遭拒」(請參閱步驟 3)。

步驟 6:檢查傳入閘道的 mTLS (如有設定)

只有在您為環境群組設定 virtualhosts[].mcpMtls 時 (Apigee hybrid 1.17.4 以上版本),才需要執行這個步驟。mTLS 問題的典型症狀是,MCP 工具呼叫一個環境群組失敗 (通常是 503 Service Unavailable),但呼叫其他環境群組成功,因為 MCP 資料層會為每個環境群組保留憑證設定。

  1. 確認操作員已接受欄位。環境群組的轉送資源必須包含 mcpMtls 區塊:
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    如果apigee-virtualhost升級後幾分鐘,第二欄仍為空白,通常表示叢集中的 Apigee 自訂資源定義版本早於1.17.4,且未宣告mcpMtls,因此 API 伺服器捨棄了該欄位。(提供監控程式映像檔的 apigee-org 圖表未升級至 1.17.4 的情況較少見)。如果升級作業為運算子圖表執行 helm upgrade,但略過「安裝更新後的 Apigee CRD」步驟,就會發生這種情況。MCP 資料層仍會使用單向 TLS,而 MUTUAL 模式中的輸入閘道會拒絕該 TLS;相同的過時 CRD 也會導致系統無法回報下一步中的 AIS_MCP_MTLS_* 問題。檢查並修正:
    kubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls   # 0 means the CRDs are stale
    kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
    從 Helm 圖表目錄執行 kubectl apply,然後再次執行環境群組的 apigee-virtualhost 升級作業。
  2. 檢查叢集回報的憑證問題。監控程式會掃描設定的 Secret,並為每個問題建立 ApigeeIssue:
    kubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)'
    kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
    Spec.Details 欄位會指出問題所屬的 Secret 和 ApigeeRouteConfig (名為 ORG_NAME-ENV_GROUP_NAME),以及具體缺陷。
    原因 嚴重性 意義 修正
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR 用戶端憑證 Secret 不存在 (secret not found)、缺少 cert 或 key 項目、項目空白或不是 PEM、憑證和金鑰不相符,或憑證的擴充金鑰用途省略 clientAuth。MCP 資料層不會載入該設定。 建立或修正 Secret (選項 2) 或 helm upgrade 後方的檔案 (選項 1);如果問題在於延伸金鑰使用方式,請使用 clientAuth 重新核發憑證。
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY 到期前 14 天內為 WARNING,之後為 ERROR 用戶端憑證即將到期或已過期。系統仍會提供過期的憑證,但輸入閘道會拒絕握手。 按照「輪換憑證」一節所述的方式輪換憑證。
    AIS_MCP_MTLS_CA_CERT_INVALID ERROR -cacert Secret 不存在 (secret not found;使用 sslSecret 時,您必須自行建立)、缺少 cacert 項目、項目不是 PEM、區塊不是憑證,或其中的憑證不是 CA 憑證。 視需要建立 Secret,並將簽署 ingress 閘道憑證的 CA 憑證 (或鏈結) 放入 cacert 項目。
    AIS_MCP_MTLS_CA_CERT_EXPIRY 到期前 14 天內為 WARNING,之後為 ERROR -cacert Secret 中的 CA 憑證即將到期或已過期。過期後,MCP 資料層就不會再信任 ingress 閘道的憑證鏈結。 在 -cacert Secret 中的 CA 憑證到期前,請替換該憑證,如果也重新核發了輸入閘道本身的憑證,請一併替換。
    Secret 修正後,系統會在下次掃描時自動撤銷問題。
  3. 閱讀 Sidecar 的 mTLS 訊息。每當 apigee-mcp-server-config 容器無法套用環境群組的憑證時,就會記錄 error 行。每行通常包含 env_group、secret (以及啟用鏈結驗證時的 trust-Secret 欄位)、reason 代碼和包裝的錯誤文字等欄位。請依 reason 程式碼值 (即穩定 ID) 篩選,不要依賴其他欄位名稱:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    搜尋整個記錄,而非最近的視窗:Sidecar 首次發現錯誤的 Secret 時會回報 (變更時也會再次回報),而非每次重新整理時都回報。

    下列原因代碼在目前版本中穩定。如果看到未列出的代碼,請與 Google Cloud Customer Care 聯絡。

    reason 意義 動作
    MCP_MTLS_SECRET_NOT_FOUND Apigee 命名空間中沒有參照的 Secret。error 文字會命名該 Secret,並指出它是用戶端還是信任 Secret。 建立 Secret 時,請使用確切名稱 (請記住信任 CA 的 -cacert 後置字串)。sidecar 會自行偵測到新的 Secret。
    MCP_MTLS_MATERIAL_UNUSABLE Secret 存在,但內容遭拒:資料金鑰遺失或空白、內容並非 PEM、憑證和金鑰不配對、用戶端憑證沒有 clientAuth,或信任 Secret 沒有 CA 憑證。系統會將相同的瑕疵回報為 ApigeeIssue (上一個步驟)。 修正 Secret 內容。編輯 Secret 會觸發新的嘗試。
    MCP_MTLS_SECRET_READ_FAILED,MCP_MTLS_SECRET_WATCH_FAILED,MCP_MTLS_SECRET_ACCESS_FAILED sidecar 無法透過 Kubernetes API 讀取或監控 Secret (API 伺服器無法使用,或 MCP 角色失去 secrets 權限)。MCP_MTLS_SECRET_READ_FAILED 行包含重試情境,而 Sidecar 會以輪詢方式重試;另外兩行則會回報 Sidecar 的 Secret 監控狀態,並在傳回存取權時記錄 MCP_MTLS_SECRET_READER_RECOVERED。 請確認 MCP 角色仍授予 secrets 上的 get、list、watch (請參閱「信任邊界」),且命名空間中的其他元件可以連線至 API 伺服器。角色名稱結尾為產生的後置字串,因此請使用 kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server 尋找。
    MCP_MTLS_PUBLISH_FAILED 憑證有效,但無法寫入 MCP Pod 的記憶體內磁碟區。sidecar 會在輪詢延遲後重試,並在寫入成功時記錄 MCP_MTLS_PUBLISH_RECOVERED。 正常運作時不應發生這種情況。如果問題持續發生,請收集 sidecar 記錄,並與 Google Cloud Customer Care 聯絡。
    MCP_MTLS_UNKEYABLE_ENV_GROUP 環境群組已設定 mcpMtls,但其 envGroupId 標籤值並非有效的路徑元素,因此 MCP 資料層會透過單向 TLS 提供群組,而 MUTUAL 模式的輸入閘道會拒絕其工具呼叫。Kubernetes 標籤規則通常會禁止這類值,因此處於這種狀態的群組來自直接套用至叢集的轉送資源。沒有 ApigeeIssue 回報此問題。 確認轉送資源含有有效的標籤:kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels。重新執行環境群組的 apigee-virtualhost 升級作業,以便從圖表重新建立資源。
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION 環境群組同時設定 disableChainValidation: true 和 disableSanValidation: false。SAN 比對作業會在鏈結驗證設定的驗證程序中進行,因此如果關閉鏈結驗證,就沒有可比對的項目,系統會忽略這項設定。圖表會拒絕這項配對,因此處於這個狀態的群組來自直接套用至叢集的自訂資源。 從環境群組的 mcpMtls 區塊中移除 disableSanValidation,或將 disableChainValidation 設回 false,並提供信任的 CA (請參閱 disableSanValidation)。
    MCP_MTLS_CONFLICTING_CONFIG 同一環境群組中的兩個轉送資源會攜帶不同的 mcpMtls 區塊,因此 MCP 資料層使用的區塊取決於路徑的處理順序。群組最終可能會提供與您設定不同的用戶端憑證,且下游不會記錄哪個區塊勝出。 重新執行環境群組的 apigee-virtualhost 升級作業,然後確認區塊與步驟 1 中的 get apigeeroutes 指令相符。群組中的每條路徑都衍生自該群組的單一 virtualhosts[] 項目,因此不一致表示資源已直接套用至叢集,或先前的升級作業僅傳播部分路徑。
    除了 MCP_MTLS_UNKEYABLE_ENV_GROUP 會將環境群組降為單向 TLS 之外,環境群組會繼續使用 Sidecar 上次成功載入的憑證。如果從未載入任何工具 (首次啟用),則在問題修正前,對該環境群組的 MCP 工具呼叫都會失敗;其他環境群組則不受影響。修正後,無須重新啟動 Pod。

    其餘 MCP_MTLS_ 個代碼則無須採取任何行動。 MCP_MTLS_CHAIN_VALIDATION_DISABLED 和 MCP_MTLS_SAN_VALIDATION_DISABLED 會記錄環境群組關閉驗證,因此在整個機群中都能找到該選項。MCP_MTLS_MATERIAL_REMOVED 是群組選擇退出後的例行清除作業,MCP_MTLS_COLLECTION_FAILED 則表示清除作業未完成,且群組的憑證檔案仍在 Pod 上;下次重新整理時會重試清除作業。

  4. 如果叢集未回報任何問題,且 sidecar 記錄檔沒有任何問題,但對環境群組的工具呼叫仍失敗,則表示其中一方拒絕了握手:
    • 如果用戶端憑證的核發者不在輸入閘道信任的 CA 中,輸入閘道會拒絕該憑證 (virtualhosts[].caCertPath 或 INGRESS_SECRET_NAME-cacert)。請使用 openssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE 驗證。
    • 如果輸入閘道的憑證未鏈結至 mcpMtls.caCertPath 或 MCP_CLIENT_SECRET_NAME-cacert 中的 CA,或主體別名不含環境群組的主機別名,MCP 資料層會拒絕該憑證。使用 openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE 進行驗證,並使用 openssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName 檢查 SAN。建議您重新核發 Ingress 閘道的憑證,使其涵蓋主機別名。 如果無法這麼做,請為該環境群組設定 mcpMtls.disableSanValidation: true,MCP 資料層就會停止檢查輸入閘道憑證上的名稱。

客服案件

如果您提交的客服案件涉及 Apigee hybrid MCP 資料層,請附上以下輸出內容,加快診斷速度:

  • kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server --all-containers --tail=1000
  • kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-server
  • kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wide和kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server。
  • 最近的 overrides.yaml 和 helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE 輸出內容 (其中 APIGEE_ORG_RELEASE_NAME 是 apigee-org 圖表的 Helm 版本名稱,可透過 helm list -n APIGEE_NAMESPACE | grep apigee-org 找到)。分享 overrides.yaml 之前,請先遮蓋機密資料,包括:
    • gcp.workloadIdentity、envs[].serviceAccountPaths 或 mcpServer.serviceAccountPath 下方的任何內嵌服務帳戶金鑰。
    • virtualhosts 下的所有 TLS 憑證或私密金鑰。
    • cassandra.auth 密碼欄位。
    • 覆寫值傳遞給運算子的任何內嵌憑證。
  • 重現問題的完整 curl 指令和回應。

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

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

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