本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
本頁說明如何在執行 1.17.0 以上版本的現有 Apigee Hybrid 叢集中啟用 Model Context Protocol (MCP)。完成這項程序後，叢集會執行新的叢內 MCP 資料平面，訊息處理器也已準備好將 MCP 工具呼叫路徑傳送至該平面。接著，您可以按照共用的 MCP 快速入門指南，部署第一個 MCP Discovery Proxy。
如要瞭解 Apigee 和 Apigee Hybrid 共用的 MCP 概念、架構和功能詳細資料，請參閱 Apigee 總覽中的 MCP。
這項程序的用途
在 Apigee Hybrid 叢集上啟用 MCP 後，系統會進行下列變更：
- 授予
apigee-watcher身分在 Apigee 控制層存取 MCP 設定的權限。將apigee-watcher服務帳戶新增至 Apigee 組織controlPlaneAccess資源的watcher_identities清單，讓 MCP Sidecar 可以從 Apigee 控制層提取 MCP 設定組合。這是控制層的變更，範圍限定於 Apigee 組織，且每個組織只需執行一次，無論為該組織提供服務的叢集數量為何。 - 新增叢內 MCP 資料層。系統會在安裝 Apigee Hybrid 的 Kubernetes 命名空間 (預設為
apigee) 中，建立一組新的 MCP Pod，以及執行這些 Pod 所需的 Kubernetes 資源 (服務、水平 Pod 自動配置器和 RBAC)。這些 Pod 會處理 MCP 工具呼叫。 - 設定訊息處理器，連線至 MCP 資料平面。Apigee 運算子會更新訊息處理器 Pod 規格，讓訊息處理器將 MCP 工具呼叫路徑導向新的叢內 MCP 資料平面。套用這項變更會觸發 Message Processor 的階段性初期測試版本 (由
ApigeeDeployment控制器管理)；在新的 PodReady之前，先前的 Pod 會繼續提供流量。只有在啟用和停用轉換時，系統才會觸發發布作業，不會在持續進行的 MCP 活動或穩定狀態的 MCP 流量中觸發。請在核准的維護期間執行這項程序，並等待版本發布完成，再繼續操作。
步驟 1：編輯 overrides.yaml
開啟用於 Apigee Hybrid Helm 圖表的 overrides.yaml 檔案。在檔案的頂層新增：
enableMcpServer: true
這是啟用 MCP 的最低設定需求。這項功能會使用 apigee-org 圖表中的內建預設值：兩個 MCP 資料平面副本，在 CPU 使用率達到 70% 時自動調度至十個，MCP 資料平面容器的資源要求為 500m CPU 和 512Mi 記憶體，限制為 2000m CPU 和 1Gi 記憶體。如要自訂副本數量、資源要求或 MCP 服務帳戶，請參閱本頁稍後的「參考資料：overrides.yaml 中的 MCP 欄位」。
以下是合併 overrides.yaml 的完整範例，每種驗證樣式各有一個範例。請使用與現有基礎安裝設定相符的範例；MCP 專屬的行會以註解標示，且在所有三種變體中都相同。
請根據基本安裝程序驗證 Apigee 元件與 Google Cloud 的方式，選取對應的分頁標籤。這項選取項目會套用至這個頁面上所有以變數為範圍的程式碼區塊。
Workload Identity (GKE)
如果基本安裝程序透過 GKE Workload Identity 將 Apigee 元件驗證至 Google Cloud，請使用這個變體 (磁碟上沒有服務帳戶金鑰檔案)。
instanceID: "my-hybrid-instance" namespace: APIGEE_NAMESPACE gcp: region: us-central1 projectID: my-hybrid-project workloadIdentity: enabled: true gsa: apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com k8sCluster: name: my-cluster region: us-central1 org: my-org envs: - name: my-env # ---- MCP: minimum required ------------------------------------------------- enableMcpServer: true # ---- MCP: optional customization (all fields default when omitted) --------- # mcpServer: # replicaCountMin: 2 # replicaCountMax: 10 # targetCPUUtilizationPercentage: 70 # resources: # requests: { cpu: 500m, memory: 512Mi } # limits: { cpu: 2000m, memory: 1Gi } # sidecar: # resources: # requests: { cpu: 200m, memory: 128Mi } # limits: { cpu: 500m, memory: 512Mi } # annotations: {} # ----------------------------------------------------------------------------
以檔案為基礎的服務帳戶金鑰
如果基本安裝程序是透過您分配給各叢集的服務帳戶金鑰檔案，將 Apigee 元件驗證至 Google Cloud，請使用這個變體。
instanceID: "my-hybrid-instance" namespace: APIGEE_NAMESPACE gcp: region: us-central1 projectID: my-hybrid-project k8sCluster: name: my-cluster region: us-central1 org: my-org guardrails: serviceAccountPath: ./service-accounts/apigee-non-prod.json mart: serviceAccountPath: ./service-accounts/apigee-non-prod.json connectAgent: serviceAccountPath: ./service-accounts/apigee-non-prod.json watcher: serviceAccountPath: ./service-accounts/apigee-non-prod.json # MCP also uses this key file envs: - name: my-env serviceAccountPaths: synchronizer: ./service-accounts/apigee-non-prod.json runtime: ./service-accounts/apigee-non-prod.json # ---- MCP: minimum required ------------------------------------------------- enableMcpServer: true # ---- MCP: optional customization (all fields default when omitted) --------- # mcpServer: # replicaCountMin: 2 # replicaCountMax: 10 # targetCPUUtilizationPercentage: 70 # resources: # requests: { cpu: 500m, memory: 512Mi } # limits: { cpu: 2000m, memory: 1Gi } # sidecar: # resources: # requests: { cpu: 200m, memory: 128Mi } # limits: { cpu: 500m, memory: 512Mi } # annotations: {} # ----------------------------------------------------------------------------
Workload Identity Federation (AKS/EKS)
如果您的基本安裝作業位於 AKS 或 EKS，並透過工作負載身分聯盟向 Google Cloud 進行驗證，請使用這個變體。MCP 會使用 apigee-watcher 已使用的憑證設定檔 (來自 watcher.serviceAccountPath)，因此您不必新增任何 MCP 專屬的身分識別設定。如果改為將憑證設定儲存在 Kubernetes 密鑰中，請參閱「其他身分識別機制」。
將 MCP 頂層金鑰新增至現有的 WIF overrides.yaml：
# ---- MCP: minimum required ------------------------------------------------- enableMcpServer: true # ---- MCP: optional customization (all fields default when omitted) --------- # mcpServer: # replicaCountMin: 2 # replicaCountMax: 10 # targetCPUUtilizationPercentage: 70 # resources: # requests: { cpu: 500m, memory: 512Mi } # limits: { cpu: 2000m, memory: 1Gi } # sidecar: # resources: # requests: { cpu: 200m, memory: 128Mi } # limits: { cpu: 500m, memory: 512Mi } # annotations: {} # ----------------------------------------------------------------------------
請勿設定 mcpServer.gsa 和 mcpServer.serviceAccountPath。MCP Sidecar 會使用與 apigee-watcher 相同的憑證設定檔，該檔案位於 watcher.serviceAccountPath。
步驟 2：在控制層授予監控者身分對 MCP 設定的存取權
MCP Sidecar 會使用 apigee-watcher 元件的 Google Cloud 服務帳戶 (您在步驟 1 中選取的身分)，從 Apigee 控制層擷取設定組合。在 MCP Pod 啟動前，請將該服務帳戶新增至 Apigee 機構 controlPlaneAccess 資源的 watcher_identities 清單。如果沒有這項授權，MCP Sidecar 對 apigee.googleapis.com 的呼叫會傳回 404 Not Found，且 MCP 資料平面永遠無法準備好服務工具流量。
這項步驟每個機構只需執行一次 (而非每個叢集)。如果您已在同一個 Apigee 機構中授予先前叢集的存取權，請略過這個步驟。
- 設定用於 API 呼叫的殼層變數。重複使用安裝項目中的值：
export ORG_NAME=YOUR_ORG_NAME export PROJECT_ID=YOUR_GCP_PROJECT_ID export WATCHER_SA=apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com export TOKEN=$(gcloud auth print-access-token)
其中：
YOUR_ORG_NAME是 Apigee Hybrid 組織的名稱。YOUR_GCP_PROJECT_ID是 Google Cloud 雲端專案，用於代管 Apigee Hybrid 組織。WATCHER_SA是apigee-watcher服務帳戶的電子郵件地址。如果您在overrides.yaml中覆寫watcher.gsa，請使用該值，而非預設的apigee-watcher@${PROJECT_ID}.iam.gserviceaccount.com。
- 呼叫 updateControlPlaneAccess API，將監控服務帳戶新增至
watcher_identities清單：沒有資料落地
curl -X PATCH -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \ -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"資料落地設定
curl -X PATCH -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess?update_mask=watcher_identities" \ -d "{\"watcher_identities\": [\"serviceAccount:${WATCHER_SA}\"]}"如果 Apigee Hybrid 安裝作業使用資料落地，
CONTROL_PLANE_LOCATION是控制層資料的位置。如需可用位置的清單，請參閱「可用的 Apigee API 控制層區域」。呼叫會傳回長時間執行的作業。請先等待作業完成，再執行下方的驗證步驟。
- 確認補助金是否已發放。呼叫 getControlPlaneAccess，並確認監控服務帳戶顯示在回應的
watcherIdentities欄位中：沒有資料落地
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"資料落地設定
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"回應應包含
watcherIdentities陣列，其中含有監控服務帳戶。例如：{ "synchronizerIdentities": [ ... ], "analyticsPublisherIdentities": [ ... ], "watcherIdentities": [ "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID.iam.gserviceaccount.com" ] }
如果回應中沒有
watcherIdentities，或不包含監控服務帳戶，請重新執行 PATCH 指令，並檢查作業狀態是否有錯誤，再繼續進行。
步驟 3：升級 apigee-operator 圖表
請先升級運算子圖表。運算子圖表擁有新 MCP 資源的結構定義，而機構圖表則會參照這些資源。如果升級順序錯誤，雖然會成功建立 helm upgrade，但不會建立 MCP Pod。
helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
指令會在不到一分鐘內完成。確認運算子 Deployment 已完全推出新映像檔 (apigee-controller-manager
Deployment 是原始 Kubernetes 資源，而非 ApigeeDeployment，因此 kubectl rollout status deploy 是這裡的正確指令)：
kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m
預期輸出內容：
deployment "apigee-controller-manager" successfully rolled out
步驟 4：升級 apigee-org 圖表
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
現在有兩個對帳迴圈會平行執行：
- Apigee 運算子會建立 MCP 部署、服務、HPA、ServiceAccount、角色和 RoleBinding。MCP Pod 會一次啟動兩個 (視 Kubernetes 排程而定)，每個 Pod 中的邊車容器會在啟動後不久，從 Apigee 控制層執行第一次設定擷取作業。
- Apigee 運算子會將
hostAliases項目插入 Message Processor Pod 規格，這會觸發apigee-runtimeApigeeDeployment的發布作業。
步驟 5：驗證安裝
確認 MCP 資料平面正在執行
檢查運算子建立的四個 MCP 相關資源。資源名稱包含衍生自機構的後置字串；下列範例使用 ORG_CR_SUFFIX 做為該後置字串的預留位置，而 Pod 後置字串和服務 ClusterIP 在您的環境中會有所不同。
MCP Pod (預設為兩個；負載量高時會自動調度至十個)：
kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME READY STATUS RESTARTS AGE apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-abc12 2/2 Running 0 2m apigee-mcp-server-default-ORG_CR_SUFFIX-6d4c8-def34 2/2 Running 0 2m
每個 Pod 的「READY」欄都必須顯示 2/2。每個 Pod 中的兩個容器分別是：
apigee-mcp-server：MP Pod 連線的 MCP 資料平面容器。apigee-mcp-server-config：設定 Sidecar (apigee-watcher二進位檔的模式)，會從 Apigee 控制層擷取設定組合，並寫入 MCP 資料層容器讀取的共用磁碟區。
MCP ApigeeDeployment (Kubernetes 自訂資源，而非一般 Deployment)：
kubectl get apigeedeployment -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME STATE NESTEDSTATE AGE apigee-mcp-server-default-ORG_CR_SUFFIX running 2m
預期狀態為 running。此外，也請確認基礎 pod 為 2/2
Running：
kubectl get pod -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME READY STATUS RESTARTS AGE apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH 2/2 Running 0 2m
MCP 服務：
kubectl get svc -n APIGEE_NAMESPACE -l app=apigee-mcp-server
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE apigee-mcp-server-default-ORG_CR_SUFFIX ClusterIP 10.96.42.17 <none> 80/TCP,443/TCP,15021/TCP,15000/TCP 2m
MCP HorizontalPodAutoscaler：
kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server
確認 MINPODS 符合 mcpServer.replicaCountMin (預設為 2)，且 MAXPODS 符合 mcpServer.replicaCountMax (預設為 10)。TARGETS、REPLICAS 和 AGE 欄取決於即時指標和叢集狀態。overrides.yaml
確認訊息處理器 Pod 是否收到 hostAliases 項目
每個 MP Pod 都必須顯示插入的項目，如果缺少任何一個 Pod，該 Pod 就無法轉送 MCP 工具呼叫。列出所有 MP Pod 和其 hostAliases：
kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
預期輸出內容：每個 MP Pod 都會列出 hostAliases 陣列，其中包含一個項目，以及兩個指向上一步中 MCP 服務 ClusterIP 的主機名稱 (第二個主機名稱使用小寫的機構名稱)。Message Processor Pod 名稱遵循 apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH 範本，其中 TRUNCATED_ORG 是貴機構的名稱 (如果機構名稱很長，會截斷以符合 Kubernetes 63 個字元的名稱限制)、ENV_GROUP_HASH 是每個環境的部署群組雜湊、REV 是目前的發布修訂版本號碼 (四位數，例如 1170)，而 POD_HASH 是每個 Pod 的隨機後置字元。例如：
apigee-runtime-myorg-env1-abc12-1170-def34 [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]] apigee-runtime-myorg-env1-abc12-1170-ghi56 [map[hostnames:[mcp.apigee.internal myorg.mcp.apigee.internal] ip:10.96.42.17]]
如有任何 Pod 顯示空白的 hostAliases 值，表示 Message Processor ApigeeDeployment 未完全擷取更新後的 Pod 規格。如要強制執行新的暫存 Canary 版本，請刪除目前的 Message Processor Pod；ApigeeDeployment 控制器會從目前的規格重新轉譯這些 Pod (現在包含 hostAliases 項目)：
kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime
ApigeeDeployment 控制器會在 1 分鐘內重新建立 Pod。請注意，kubectl rollout restart deploy (原始 Kubernetes 指令) 無法在 Message Processor 上運作，因為 Message Processor 是以 ApigeeDeployment 自訂資源的形式部署，而非 Deployment。
安裝完成
上述三項檢查會共同確認 MCP 資料平面正在執行，且 MP 可定址：
- 每個 MCP Pod 都是
2/2 Running。如果未載入運算子發出的 TLS 憑證，且 Sidecar 尚未載入初始 MCP 設定，MCP 資料平面容器就會在通訊埠15021上，讓 Kubernetes readiness 探測失敗，因此ReadyPod 必須同時滿足這兩項先決條件。 - 每個 MP Pod 的規格都包含
hostAliases項目，將mcp.apigee.internal和ORG_NAME.mcp.apigee.internal固定至 MCP Service ClusterIP。因此，MP Pod 可以將 MCP Proxy 目標端點解析為叢集內 MCP 資料平面。 - MP Pod 會透過注入的
hostAliases項目，將mcp.apigee.internal解析為 MCP 服務 ClusterIP。
部署第一個 MCP Discovery Proxy 後，您會驗證端對端 MCP 工具流量 (透過 Apigee Ingress 實際進行 MCP initialize 或 tools/list 呼叫)，這是共用 MCP 快速入門的一部分。
如果前三項檢查有任何一項失敗，請先參閱「排解 MCP 部署作業問題」，再繼續進行快速入門。
步驟 6：在剩餘的叢集上啟用 MCP
特定主機名稱的 MCP 要求可以轉送至任何提供相應 Apigee 環境群組的叢集。如果 MCP 在某些叢集上啟用，但在同一個環境群組中的其他叢集上未啟用，則路由至未啟用 MCP 的叢集的 MCP 要求會失敗 (通常會以 503 Service Unavailable 回傳至用戶端)。
在提供相同環境群組服務的每個叢集上，統一啟用 MCP。 如要新增叢集，請重複執行步驟 1、3、4 和 5。您不需要重複步驟 2 (授予監控者身分存取權)：這項授權的範圍是 Apigee 機構，適用於同一機構中的所有叢集。
復原
如要在叢集上停用 MCP，請在 overrides.yaml 中設定 enableMcpServer: false (或完全移除該欄位)，然後升級 apigee-org 圖表：
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml
enableMcpServer 欄位只會由 apigee-org 圖表使用，因此停用時不需要升級運算子圖表。Apigee 運算子 (未變更) 會從 ApigeeOrganization 自訂資源中擷取設定變更，刪除 MCP 資源，並從訊息處理器 Pod 規格中移除 hostAliases 項目，進而觸發 apigee-runtime ApigeeDeployment 的發布作業。在核准的維護期間內復原。
回溯後，您部署至 Apigee 環境的 MCP 探索 Proxy 仍會出現在 Apigee 控制層，但該環境群組中的任何叢集都不會處理 MCP 流量。取消部署 MCP Discovery Proxy，即可完全停用這項功能，或保留部署的 Proxy，稍後再重新啟用叢集上的 MCP。
參考資料：overrides.yaml 中的 MCP 欄位
下表列出每個 Apigee Hybrid overrides.yaml 欄位，這些欄位會控管 1.17.0 版中的 MCP 行為。只有 enableMcpServer 為必填，其他欄位則有適合大多數安裝作業的安全預設值。
欄位定義符合混合式 1.17.0 的 apigee-org Helm 資訊套件預設值。
| 欄位 | 類型 | 預設 | 建議的調整方式 |
|---|---|---|---|
enableMcpServer |
布林值 | false |
必要。設為 true 即可在這個叢集上啟用 MCP。切換這個欄位會觸發訊息處理器的階段性初期測試版發布作業。請只在維護期間切換，並等待版本發布完成後再繼續操作。 |
mcpServer.replicaCountMin |
整數 | 2 |
請繼續使用 2 進行 HA。只有在 MCP 流量偏高時才增加，因為 HPA 會在 CPU 壓力下自動擴充。信號：持續 HPA
在 replicaCountMax，且 CPU 高於目標。 |
mcpServer.replicaCountMax |
整數 | 10 |
如果觀察到 HPA 在尖峰時段達到 10 上限，請增加預算。信號：
kubectl top pods -l app=apigee-mcp-server 顯示 CPU 達到上限附近的所有 Pod。如果未安裝 metrics-server，請使用 kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server，並檢查 REPLICAS 欄是否達到 MAXPODS 上限。 |
mcpServer.targetCPUUtilizationPercentage |
整數 | 70 |
降低至 50–60，適用於容易受到延遲影響的工作負載 (會提早擴充)。將值調高至 80 到 85，即可減少預算有限的叢集中的副本數量。信號：要求延遲時間 (第 95 個百分位數) 與每個 Pod 的 CPU 使用率相關。 |
mcpServer.resources.requests |
ResourceList | cpu: 500m, memory: 512Mi |
如果 Pod 經常在穩定狀態下因記憶體不足而遭終止，或是 CPU 受到節流，請增加要求。信號：kubectl describe pod 顯示 OOMKilled 或節流條件。 |
mcpServer.resources.limits |
ResourceList | cpu: 2000m, memory: 1Gi |
如果 P95 延遲時間較長，但整體每秒查詢次數較低 (要求數量少但費用高)，請先提高 CPU 上限，再提高副本數量。只有在看到 OOMKills 時，才提高記憶體上限。 |
mcpServer.sidecar.resources.requests |
ResourceList | cpu: 200m, memory: 128Mi |
很少需要調整。Sidecar 會定期編寫及寫入設定組合，穩定狀態的 CPU 消耗量極低。 |
mcpServer.sidecar.resources.limits |
ResourceList | cpu: 500m, memory: 512Mi |
很少需要調整。只有在單一 Discovery Proxy 中部署異常大量的 MCP 工具時，才需要增加記憶體。 |
mcpServer.terminationGracePeriodSeconds |
整數 | 30 |
很少需要調整。如果長期處理中的 MCP 要求在 Pod 排空期間需要更多時間才能完成，請增加此值。 |
mcpServer.annotations |
地圖 | {} |
如果叢集需要額外的 Pod 註解，請新增這些註解。 |
mcpServer.serviceAccountPath |
字串 | 未設定 | 除非需要依元件區隔身分，否則請勿設定。如果未設定，MCP 會使用 watcher.serviceAccountPath。MCP 不會使用 envs[].serviceAccountPaths.runtime。apigee-watcher
身分已具備 MCP Sidecar 所需的權限。如要覆寫這個欄位，請指定 Google Cloud 服務帳戶金鑰 JSON 檔案的路徑。與 mcpServer.gsa 互斥。如果未啟用 Workload Identity，且您未設定 mcpServer.serviceAccountRef 或 serviceAccountSecretProviderClass，則必須設定 mcpServer.serviceAccountPath 或 watcher.serviceAccountPath。如果兩者皆未設定，helm upgrade 會失敗並顯示 mcpServer.serviceAccountPath or watcher.serviceAccountPath is
required!! 錯誤。盡可能使用 Workload Identity (GKE) 或 Workload Identity Federation (AKS/EKS)。您必須輪替以檔案為準的服務帳戶金鑰、安全地儲存金鑰、將金鑰分配給每個叢集，且金鑰是最常見的支援構件外洩來源 (請參閱「支援服務案件」)。 |
mcpServer.gsa |
字串 | 未設定 | 除非需要依元件區隔身分，否則請勿設定。如未設定，MCP 會改回使用 watcher.gsa，然後使用 gcp.workloadIdentity.gsa。apigee-watcher 身分已具備 MCP Sidecar 所需的權限，因此建議重複使用。只有在貴機構因稽核原因，需要為 MCP Sidecar 提供不同的身分時，才使用專屬的 Google Cloud 服務帳戶電子郵件進行覆寫。 |
mcpServer.serviceAccountRef |
字串 | 未設定 | 精確。Apigee 命名空間中現有 Kubernetes Secret 的名稱，其中包含 MCP Sidecar 的 Google Cloud 服務帳戶金鑰。只有在 Apigee Helm 資訊套件外部管理服務帳戶金鑰 Secret 時，才需要使用這項設定。與 mcpServer.serviceAccountPath 和 mcpServer.gsa 互斥。MCP 不會使用 watcher.serviceAccountRef。如果您的基本安裝作業將 apigee-watcher 金鑰儲存在 Kubernetes 密鑰中，並使用 watcher.serviceAccountRef，請將這個屬性設為相同的密鑰名稱。 |
mcpServer.podDisruptionBudget |
地圖 | 未設定 | MCP Pod 的選用 PodDisruptionBudget。接受 minAvailable 或 maxUnavailable (整數或百分比字串)。請設定其中一個，不要同時設定。除非叢集有嚴格的自願性中斷政策，需要明確的預算，否則請勿設定。 |
mcpServer.tolerations |
list | unset (返回頂層 tolerations) |
MCP Pod 的標準 Kubernetes 容許條件。只有在 MCP Pod 必須容許其他 Apigee 元件不容許的汙點時，才需要設定。 |
mcpServer.image.pullPolicy |
字串 | IfNotPresent |
MCP 伺服器容器的映像檔提取政策。很少變更。 |
mcpServer.sidecar.image.pullPolicy |
字串 | IfNotPresent |
MCP 邊車容器的映像檔提取政策。很少變更。 |
預估 MCP 工具容量
Apigee Hybrid 不會強制規定每個機構的 MCP 工具數量上限。工具容量受限於四個硬性大小限制，這些限制會在部署或要求時強制執行。可容納的工具數量取決於每個工具的大小，而工具大小則衍生自定義工具的 OpenAPI 規格。
正常電池容量
對於大多數 OpenAPI 規格 (混合使用各種工具，參數計數、要求主體大小和說明長度各不相同，且大多數工具都屬於中小尺寸範圍)，在預設 tools/list 回覆大小限制下，每個機構通常可容納 10,000 個 MCP 工具。
實際容量會因 OpenAPI 規格的具體形狀而異。如果機構的規格以多項參數、大型要求主體或長說明為主，則在達到下列四項硬性限制之一前，可容納的工具數量會成比例減少。如要驗證特定規格的容量，請按照下方的「估算規格容量」一節操作。
硬性限制
Apigee Hybrid 版本 1.17.0 適用四種大小限制。以最低適用限制為準，提高其中一項限制不會影響其他限制。
| 限制 | 值 | 範圍 | 故障模式 |
|---|---|---|---|
| OpenAPI 規格檔案大小 | 3 MiB | 每個 .yaml 檔案 |
400 at proxy validate |
| MCP Proxy 套件大小 (解壓縮後) | 50 MiB | 每個 MCP Discovery Proxy | 400 at proxy validate |
tools/list 回應大小 |
10 MiB (預設) | 每個主機名稱 | 502TooBigBody |
| 每個環境群組的主機名稱 | 100 | 每個環境群組 | 400 環境群組更新 |
工具大小的決定因素
每個工具的大小幾乎完全由工具的 inputSchema 組成，而這項資料是從作業的 OpenAPI 規格 parameters 和 requestBody 衍生而來。最重要的三項屬性：
- 參數數量。每個參數項目大約會為
tools/list回應中的工具大小貢獻 100 個位元組。 - 要求主體屬性數量。每個要求主體屬性約佔 100 個位元組。因此，含有要求主體的作業 (通常是
POST和PUT) 比沒有要求主體的作業 (通常是GET和DELETE) 大得多。 - 說明長度。作業說明幾乎會逐字複製到工具中，因此說明越長，工具大小就越大。
回應結構定義不會計入大小預算。只有 parameters 和 requestBody 會傳送至 MCP 設定。因此，單純根據 OpenAPI 檔案大小估算容量，往往會高估成本，因為大多數實際的 OpenAPI 規格都包含不會影響工具大小的回覆結構定義。
預估規格的容量
如要估算 OpenAPI 規格的工具容量，最可靠的方法是評估代表性子集：
- 部署 MCP 探索 Proxy，參照您打算發布的工具中，一小部分具代表性的子集 (例如 50 到 100 個工具，反映完整規格中的參數計數、要求主體大小和說明長度組合)。
- 對已部署的 Proxy 呼叫
tools/list，並記錄回應大小 (以位元組為單位) 和傳回的工具數量。 - 將回應大小除以工具數量，即可取得規格中每個工具的平均大小。
- 將適用的
tools/list回應大小上限 (預設為 10 MiB) 除以該平均值，即可估算一個主機名稱可容納的工具數量上限 (規格為這個形狀)。
增加容量
有兩種機制可將工具容量擴充至預設值以上：
- 在主機名稱之間共用工具。
tools/list每個主機名稱的回應上限為 100 則。在同一個環境群組中，將工具分散到多個主機名稱，可增加每個主機名稱的空間 (但每個環境群組最多只能有 100 個主機名稱)。分片不會提高每個 Proxy 組合的限制；在單一 MCP Discovery Proxy 上，所有主機名稱仍適用 50 MiB 的組合上限。 - 提高
tools/list回應大小上限。每個主機名稱的預設上限為 10 MiB。你可以將上限提高至 30 MiB。至少要設定overrides.yaml中的envs.components.runtime.resources.limits.memory、envs.components.runtime.resources.requests.memory和envs.components.runtime.cwcAppend.bin_setenv_max_mem，然後在apigee-org圖表上執行helm upgrade。如需完整程序，包括每個環境與整個安裝項目的變體、訊息處理器堆積大小調整指南，以及完整的overrides.yaml範例，請參閱「在 Apigee Hybrid 中設定大型訊息酬載支援」。提高回應限制不會影響 50 MiB MCP 代理程式套件大小限制；如果您的容量受限於該限制，這項變更就沒有幫助。
安全性
信任邊界
MCP 資料平面會在您自己的 Kubernetes 叢集中執行。Google 無法在執行階段存取資料平面。Apigee 控制層會根據 OpenAPI 規格提供 MCP 設定，但不會監控 MCP 請求流量。靜態設定資料會儲存在 Apigee 代管的 Cloud Storage bucket 中，並限定於您的 Apigee 租戶專案，MCP Sidecar 會使用其環境 Google Cloud 服務帳戶擷取資料。
Apigee 運算子會在 Apigee 命名空間 (APIGEE_NAMESPACE) 中，為 MCP 資料平面 ServiceAccount 佈建 MCP 範圍的 Kubernetes Role 和 RoleBinding。這個角色授予唯讀存取權：
get、list、watch，位於核心 API 群組的services中。get、list、watch(apigeeroutesapigee.cloud.google.comAPI 群組)。
這個角色不會授予任何寫入動詞，也無法存取 Secrets、ConfigMaps 或 Pod 狀態。稽核人員可使用下列指令，直接從叢集驗證確切規則：
APIGEE_ORG_CR=$(kubectl get apigeeorganization -n APIGEE_NAMESPACE \ -o jsonpath='{.items[0].metadata.name}') kubectl get role,rolebinding -n APIGEE_NAMESPACE \ --field-selector metadata.name=apigee-mcp-server-$APIGEE_ORG_CR -o yaml
apigee-mcp-server-APIGEE_ORG_CR Role 和 RoleBinding 是 MCP 範圍的 RBAC 資源，其名稱包含 ApigeeOrganization 自訂資源的全名 (衍生自 Apigee 機構名稱和簡短雜湊)。資源層級沒有 app=apigee-mcp-server 標籤 (只有 Pod 有)，因此以標籤為依據的查詢不會傳回任何結果。如果上述欄位選取器指令未傳回任何內容，請使用下列指令列出命名空間中所有與 MCP 相關的 RBAC 資源：
kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server
訊息處理器與 MCP 資料平面之間的 TLS
訊息處理器 Pod 會在 https://mcp.apigee.internal/ 或 https://ORG_NAME.mcp.apigee.internal/ 撥號 MCP 資料層。這些主機名稱會透過插入的 hostAliases 項目，解析為 MCP 服務 ClusterIP。MCP 資料平面容器會提供由 Apigee-operator 佈建的簽發者 (名為 apigee-ca-issuer 的 ClusterIssuer) 簽署的 TLS 憑證。憑證的主體別名包含兩個主機名稱。
限制對 MCP 服務的連入存取權
在 Apigee Hybrid 1.17.0 中，MCP 資料層不會獨立驗證呼叫端。並信任傳送至該伺服器的要求，都已由訊息處理器中執行的 Apigee MCP Proxy 驗證。MCP 服務的唯一預期呼叫端是訊息處理器。任何其他可透過 TCP 443 存取 MCP 服務 ClusterIP 的叢集內工作負載，都能叫用 MCP 工具，不必進行驗證檢查。
將 MCP Pod 的連入存取權限制為僅限 Message Processor Pod，方法是使用平台叢集 Ingress 政策引擎 (Kubernetes NetworkPolicy、Cilium、Calico、Istio AuthorizationPolicy 或同等項目)。限制：
- 允許從相同命名空間中具有標籤
app=apigee-runtime的 Pod，透過 TCP443，將 Ingress 傳送至命名空間APIGEE_NAMESPACE中具有標籤app=apigee-mcp-server的 Pod。 - 拒絕 TCP
443上所有其他對標籤為app=apigee-mcp-server的 Pod 輸入流量。 - 拒絕所有叢集內輸入的 TCP
15021，傳送至標籤為app=apigee-mcp-server的 Pod。kubelet 會使用埠15021提供的未經驗證純 HTTP/healthz/ready端點進行就緒探查；kubelet 會直接透過 Pod IP 存取該端點，因此叢集內的其他工作負載不應透過15021存取 MCP Pod。
完成 MCP 快速入門並在非開發環境中部署第一個 MCP 探索 Proxy 之前，請先套用這項限制。
設定更新合約
MCP Sidecar 成功提取設定後，MCP 資料平面容器會載入提取的套件，並持續提供服務，直到下次成功提取為止。如果後續提取作業失敗 (Apigee 控制層無法連線、Cloud Storage 無法連線、監控服務帳戶的 IAM 權限已移除，或提取管道的任何其他階段發生錯誤)，Sidecar 會無限期地繼續提供最後一個已知良好的套件。1.17.0 沒有內建的陳舊上限：Pod 會保持 Ready 狀態，且 MCP 工具流量會繼續針對陳舊的套件提供服務。如果設定停止重新整理，側車記錄行會顯示 ERROR 層級的 consecutive_failures 計數器 (如需側車在每個失敗階段發出的特定訊息，請參閱「排解 MCP 部署作業問題」)。
對於受監管的生產環境，請在重複遞增此計數器的頁面上。最低可行警示：當任何 MCP 邊車容器發出 ERROR 級別的記錄行，且 consecutive_failures 達到您根據過時容許度設定的門檻時，系統就會發出警示。值上升表示 Sidecar 已停止重新整理設定，但 Sidecar 會繼續提供最後一次成功擷取的套件。
如果 Sidecar 已停止重新整理設定，請從 Sidecar 記錄中調查失敗模式；請參閱「排解 MCP 部署作業問題」。彈跳 MCP Pod 無法解決底層的擷取問題，因為新建立的 Pod 會使用相同的擷取路徑。
傳出網路需求
MCP Sidecar (每個 MCP Pod 內的設定容器) 需要透過 TCP 443 對下列端點進行連出網路存取。請根據 Apigee 機構是否使用資料落地功能，選取相符的分頁，因為所需端點會有所不同。
沒有資料落地
| 端點 | 適用於： |
|---|---|
apigee.googleapis.com |
每次重新整理設定時，請從 Apigee 控制層擷取貴機構目前的 MCP 設定參照。 |
storage.googleapis.com |
從 Google Cloud Storage 下載貴機構的 MCP 設定。 |
資料落地設定
如果您的 Apigee 機構使用資料落地，MCP Sidecar 會連線至區域 Apigee 控制平面端點 (與其他 Apigee Hybrid 元件使用的端點相同，透過 overrides.yaml 中的 contractProvider 圖表值設定)。請將 CONTROL_PLANE_LOCATION 替換為貴機構的控制平面位置 (例如 us、eu)。
| 端點 | 適用於： |
|---|---|
CONTROL_PLANE_LOCATION-apigee.googleapis.com |
每次重新整理設定時，請從貴機構的區域 Apigee 控制平面端點，擷取目前的 MCP 設定參照。 |
storage.googleapis.com |
從 Google Cloud Storage 下載貴機構的 MCP 設定。值區位於貴機構的區域，Cloud Storage 會自動將資料傳送至該值區。 |
此外，側車必須能夠為 Pod 執行的環境憑證取得 Google Cloud 存取權權杖 (透過 Workload Identity 或以檔案為基礎的服務帳戶金鑰)。具體的權杖交換端點取決於您的驗證路徑，與叢集中其他 Apigee Hybrid 元件使用的端點相同。如果從這個命名空間傳送至 Google Cloud API 的現有 Apigee Hybrid 流量成功，MCP Sidecar 的權杖交換也會成功。
此外，為了發布存活和就緒狀態，Sidecar 需要叢集內存取 Kubernetes API 伺服器 (透過標準叢集內服務位址)。這類流量絕不會離開叢集。
疑難排解
如需完整的診斷檢查清單，請參閱「排解 MCP 部署作業問題」，其中包含 Apigee Hybrid 的 叢集端診斷檢查清單。
常見安裝失敗問題
| 問題 | 原因和修正方式 |
|---|---|
helm upgrade 完成，但未顯示 MCP 資源。 |
組織圖升級時間早於作業人員圖表。先執行
helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/
，然後重新執行
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/。 |
MCP Pod 卡在 ContainerCreating 或 1/2 Ready 狀態。 |
常見原因有二：MCP 的 cert-manager Certificate 尚未發行，或是容器映像檔提取失敗。在受影響的 Pod 上執行 kubectl describe pod，找出確切原因。 |
每個意見調查都會提供 Sidecar (apigee-mcp-server-config) 記錄報表
no MCP config from CP yet; skipping tick, pod stays Ready via seed
。 |
如果貴機構尚未部署 MCP 探索 Proxy，預期會處於穩定狀態。Apigee 控制層會傳回空白的設定參照，而 MCP 資料平面只會在通訊埠 15021 上載入 Kubernetes readiness 監聽器；MCP 要求通訊埠 8443 尚未有監聽器，且對 https://mcp.apigee.internal/mcp 的要求會遭到拒絕，無法接收連線。如要轉換為服務狀態，請按照 MCP 快速入門導覽課程，將 MCP Discovery Proxy 部署至這個叢集服務的環境群組。 |
Sidecar 記錄會回報內嵌 HTTP 403 或 PermissionDenied 的 CP fetch failed。 |
Apigee 監控程式 Google Cloud 服務帳戶在 Apigee 租戶專案中，已失去 roles/apigee.runtimeAgent 角色 (該角色會授予 Sidecar apigee.runtimeconfigs.get 權限)。Apigee Hybrid 基本安裝程序會自動授予這個角色；如果 IAM 自動掃描已移除這個角色，請在 apigee-watcher Google Cloud 服務帳戶上重新套用。 |
Sidecar 記錄會回報 CP fetch failed，並顯示
context deadline exceeded、DNS 錯誤或 TLS 錯誤。 |
Sidecar 無法從叢集內部連線至 apigee.googleapis.com 或 storage.googleapis.com。根據上方的「傳出網路需求」列出的三個端點，驗證輸出流量。 |
helm upgrade 後，訊息處理器 Pod 未重新啟動。 |
確認每個 MP Pod 上都有 hostAliases 項目：
kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o
jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'。
如果任何 Pod 顯示空白，請刪除 Pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime) 強制重新算繪。ApigeeDeployment 控制器會根據目前的規格 (包括 hostAliases 項目) 重新建立 Pod。請勿使用 kubectl rollout restart deploy，因為這不適用於 ApigeeDeployment。 |
MCP 工具流量開始透過快速入門流動後，MP Pod 記錄會顯示撥打 https://mcp.apigee.internal/ 或 https://ORG_NAME.mcp.apigee.internal/ 的 TLS 握手錯誤。 |
MCP 資料平面容器提供的憑證，其主體別名 (SAN) 不包含 MP 撥號的主機名稱。驗證憑證：
kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server，然後
kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml。憑證的 dnsNames 必須包含 mcp.apigee.internal 和小寫的 ORG_NAME.mcp.apigee.internal。如果沒有，請刪除 MCP
Certificate 資源，並讓 cert-manager 重新發行。 |
後續步驟
- 請按照 MCP 快速入門指南 部署第一個 MCP Discovery Proxy，並從 MCP 用戶端呼叫 MCP 工具。
- 瞭解如何透過 API 產品管理 MCP 工具存取權。
- 瞭解如何監控及分析 MCP 流量。
- 如需進階診斷，請參閱 MCP 疑難排解指南。