Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Auf dieser Seite wird beschrieben, wie Sie das Model Context Protocol (MCP) in einem vorhandenen Apigee Hybrid-Cluster mit Version 1.17.0 oder höher aktivieren. Nach Abschluss dieses Verfahrens führt Ihr Cluster eine neue clusterinterne MCP-Datenebene aus und Ihr Message Processor ist bereit, MCP-Toolaufrufe an sie weiterzuleiten. Anschließend können Sie Ihren ersten MCP-Discovery-Proxy bereitstellen. Folgen Sie dazu der MCP-Kurzanleitung.
Informationen zu MCP-Konzepten, zur Architektur und zu Funktionen, die von Apigee und Apigee Hybrid gemeinsam genutzt werden, finden Sie in der Übersicht zu MCP in Apigee.
Was dieses Verfahren bewirkt
Wenn Sie MCP auf einem Apigee Hybrid-Cluster aktivieren, werden die folgenden Änderungen vorgenommen:
- Gewährt der Identität
apigee-watcherZugriff auf die MCP-Konfiguration auf der Apigee-Steuerungsebene. Sie fügen das Dienstkontoapigee-watcherder Listewatcher_identitiesfür die RessourcecontrolPlaneAccessIhrer Apigee-Organisation hinzu, damit der MCP-Sidecar MCP-Konfigurations-Bundles von der Apigee-Steuerungsebene abrufen kann. Dies ist eine Änderung der Steuerungsebene, die auf die Apigee-Organisation beschränkt ist. Sie ist ein einmaliger Schritt pro Organisation, unabhängig davon, wie viele Cluster diese Organisation bedienen. - Fügt eine neue clusterinterne MCP-Datenebene hinzu. Im selben Kubernetes-Namespace, in dem Apigee Hybrid installiert ist (standardmäßig
apigee), wird ein neuer Satz von MCP-Pods erstellt, zusammen mit den unterstützenden Kubernetes-Ressourcen (Service, Horizontal Pod Autoscaler und RBAC), die für die Ausführung erforderlich sind. MCP-Toolaufrufe werden von diesen Pods verarbeitet. - Konfiguriert den Message Processor so, dass er die MCP-Datenebene erreicht. Der Apigee-Operator aktualisiert die Pod-Spezifikation des Message Processors, sodass der Message Processor MCP-Toolaufrufe an die neue clusterinterne MCP-Datenebene weiterleitet. Wenn Sie diese Änderung anwenden, wird ein gestaffeltes Canary-Release des Message Processor ausgelöst (verwaltet vom
ApigeeDeployment-Controller). Der vorherige Pod verarbeitet weiterhin Traffic, bis der neue PodReadyist. Der Release wird nur bei den Übergängen zum Aktivieren und Deaktivieren ausgelöst, nicht bei laufenden MCP-Aktivitäten oder gleichbleibendem MCP-Traffic. Führen Sie dieses Verfahren in einem genehmigten Wartungsfenster aus und warten Sie, bis der Release abgeschlossen ist, bevor Sie fortfahren.
Schritt 1: overrides.yaml bearbeiten
Öffnen Sie die Datei overrides.yaml, die Sie für Ihre Apigee Hybrid-Helm-Diagramme verwenden. Fügen Sie auf der obersten Ebene der Datei Folgendes hinzu:
enableMcpServer: true
Dies ist die Mindestkonfiguration, die zum Aktivieren von MCP erforderlich ist. Es werden die integrierten Standardwerte aus dem apigee-org-Diagramm verwendet: zwei MCP-Datenebenenreplikate, die bei einer CPU-Auslastung von 70 % automatisch auf zehn skaliert werden, mit Ressourcenanfragen von 500 m CPU und 512 Mi Arbeitsspeicher und Limits von 2.000 m CPU und 1 Gi Arbeitsspeicher im MCP-Datenebenencontainer. Informationen zum Anpassen der Anzahl der Replikate, der Ressourcenanfragen oder des MCP-Dienstkontos finden Sie weiter unten auf dieser Seite unter Referenz: MCP-Felder in overrides.yaml.
Im Folgenden finden Sie vollständige Beispiele für eine zusammengeführte overrides.yaml, jeweils eines für jeden Authentifizierungsstil. Verwenden Sie das Beispiel, das der Konfiguration Ihrer vorhandenen Basisinstallation entspricht. Die MCP-spezifischen Zeilen sind mit Kommentaren hervorgehoben und in allen drei Varianten gleich.
Wählen Sie den Tab aus, der der Authentifizierung von Apigee-Komponenten bei Google Cloud in Ihrer Basisinstallation entspricht. Die Auswahl gilt für jeden Codeblock auf dieser Seite, der sich auf eine Variante bezieht.
Workload Identity (GKE)
Verwenden Sie diese Variante, wenn Ihre Basisinstallation Apigee-Komponenten über GKE Workload Identity bei Google Cloud authentifiziert (keine Dienstkonto-Schlüsseldateien auf dem Laufwerk).
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. 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: {} # ----------------------------------------------------------------------------
Dateibasierte Dienstkontoschlüssel
Verwenden Sie diese Variante, wenn Ihre Basisinstallation Apigee-Komponenten bei Google Cloud über Dienstkontoschlüsseldateien authentifiziert, die Sie an jeden Cluster verteilen.
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-Föderation (AKS/EKS)
Verwenden Sie diese Variante, wenn sich Ihre Basisinstallation auf AKS oder EKS befindet und sich über die Workload Identity-Föderation bei Google Cloud authentifiziert. MCP verwendet die Konfigurationsdatei für Anmeldedaten, die apigee-watcher bereits verwendet, aus watcher.serviceAccountPath. Sie müssen also keine MCP-spezifische Identitätskonfiguration hinzufügen. Wenn Sie die Konfiguration der Anmeldedaten stattdessen in einem Kubernetes-Secret speichern, finden Sie weitere Informationen unter Andere Identitätsmechanismen.
Fügen Sie den MCP-Schlüssel auf oberster Ebene zu Ihrer vorhandenen WIF-overrides.yaml hinzu:
# ---- 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: {} # ----------------------------------------------------------------------------
Lassen Sie mcpServer.gsa und mcpServer.serviceAccountPath unbestimmt. Der MCP-Sidecar verwendet dieselbe Konfigurationsdatei für Anmeldedaten wie apigee-watcher aus watcher.serviceAccountPath.
Schritt 2: Der Watcher-Identität Zugriff auf die MCP-Konfiguration auf der Steuerungsebene gewähren
Der MCP-Sidecar ruft sein Konfigurations-Bundle von der Apigee-Steuerungsebene über das Google Cloud-Dienstkonto der apigee-watcher-Komponente ab (die Identität, die Sie in Schritt 1 ausgewählt haben). Fügen Sie dieses Dienstkonto vor dem Start der MCP-Pods der Liste watcher_identities in der Ressource controlPlaneAccess Ihrer Apigee-Organisation hinzu. Ohne diese Berechtigung geben die Aufrufe des MCP-Sidecars an apigee.googleapis.com zum Abrufen der MCP-Konfigurationsreferenz 404 Not Found zurück und die MCP-Datenebene ist nie bereit, Tool-Traffic zu verarbeiten.
Dieser Schritt muss nur einmal pro Organisation ausgeführt werden (nicht pro Cluster). Überspringen Sie diesen Schritt, wenn Sie bereits Zugriff für einen vorherigen Cluster in derselben Apigee-Organisation gewährt haben.
- Legen Sie die Shell-Variablen fest, die Sie für den API-Aufruf verwenden. Verwenden Sie die Werte aus Ihrer Installation wieder:
export ORG_NAME=YOUR_ORG_NAME export PROJECT_ID=YOUR_GCP_PROJECT_ID export WATCHER_SA=apigee-watcher@${PROJECT_ID}. export TOKEN=$(gcloud auth print-access-token)
Wobei:
YOUR_ORG_NAMEist der Name Ihrer Apigee Hybrid-Organisation.YOUR_GCP_PROJECT_IDist das Google Cloud-Projekt, in dem Ihre Apigee Hybrid-Organisation gehostet wird.WATCHER_SAist die E-Mail-Adresse desapigee-watcher-Dienstkontos. Wenn Siewatcher.gsainoverrides.yamlüberschrieben haben, verwenden Sie diesen Wert anstelle des Standardwertsapigee-watcher@${PROJECT_ID}..
- Rufen Sie die API updateControlPlaneAccess auf, um das Watcher-Dienstkonto der Liste
watcher_identitieshinzuzufügen:Kein Datenstandort
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}\"]}"Datenstandort
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}\"]}"Dabei ist
CONTROL_PLANE_LOCATIONder Standort für Ihre Daten der Steuerungsebene, wenn Ihre Apigee Hybrid-Installation den Datenstandort verwendet. Eine Liste der verfügbaren Standorte finden Sie unter Verfügbare Regionen der Apigee API-Steuerungsebene.Der Aufruf gibt einen Vorgang mit langer Ausführungszeit zurück. Warten Sie, bis der Vorgang abgeschlossen ist, bevor Sie den folgenden Bestätigungsschritt ausführen.
- Prüfen Sie, ob die Gewährung erfolgt ist. Rufen Sie getControlPlaneAccess auf und prüfen Sie, ob das Watcher-Dienstkonto im Feld
watcherIdentitiesder Antwort angezeigt wird:Kein Datenstandort
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"Datenstandort
curl -X GET -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ "https://${CONTROL_PLANE_LOCATION}-apigee.googleapis.com/v1/organizations/${ORG_NAME}/controlPlaneAccess"Die Antwort sollte ein
watcherIdentities-Array mit Ihrem Watcher-Dienstkonto enthalten. Beispiel:{ "synchronizerIdentities": [ ... ], "analyticsPublisherIdentities": [ ... ], "watcherIdentities": [ "serviceAccount:apigee-watcher@YOUR_GCP_PROJECT_ID." ] }
Wenn
watcherIdentitiesin der Antwort fehlt oder Ihr Watcher-Dienstkonto nicht enthält, führen Sie den PATCH-Befehl noch einmal aus und prüfen Sie den Vorgangsstatus auf Fehler, bevor Sie fortfahren.
Schritt 3: apigee-operator-Diagramm aktualisieren
Aktualisieren Sie zuerst das Operator-Diagramm. Das Operator-Diagramm enthält das Schema für die neuen MCP-Ressourcen. Das Organisationsdiagramm verweist darauf. Ein Upgrade in der falschen Reihenfolge führt zu einem erfolgreichen helm upgrade, bei dem keine MCP-Pods erstellt werden.
helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
Der Befehl wird in weniger als einer Minute ausgeführt. Prüfen Sie, ob das Operator-Deployment vollständig mit dem neuen Image bereitgestellt wurde. Das apigee-controller-manager Deployment ist eine Vanilla-Kubernetes-Ressource, keine ApigeeDeployment. Daher ist kubectl rollout status deploy hier der richtige Befehl:
kubectl rollout status deploy -n APIGEE_NAMESPACE apigee-controller-manager --timeout=2m
Erwartete Ausgabe:
deployment "apigee-controller-manager" successfully rolled out
Schritt 4: apigee-org-Diagramm aktualisieren
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE \ --atomic \ -f overrides.yaml
Zwei Abgleichsschleifen werden jetzt parallel ausgeführt:
- Der Apigee-Operator erstellt das MCP-Deployment, den Dienst, das HPA, das ServiceAccount, die Rolle und das RoleBinding. MCP-Pods werden jeweils zu zweit gestartet (abhängig von der Kubernetes-Planung). Der Sidecar-Container in jedem Pod führt kurz nach dem Start den ersten Konfigurationsabruf von der Apigee-Steuerungsebene aus.
- Der Apigee-Operator fügt den Eintrag
hostAliasesin die Pod-Spezifikation des Message Processors ein, wodurch ein Release derApigeeDeploymentvonapigee-runtimeausgelöst wird.
Schritt 5: Installation prüfen
Prüfen, ob die MCP-Datenebene ausgeführt wird
Prüfen Sie die vier MCP-bezogenen Ressourcen, die der Operator erstellt hat. Ressourcennamen enthalten ein von der Organisation abgeleitetes Suffix. In den folgenden Beispielen wird ORG_CR_SUFFIX als Platzhalter für dieses Suffix verwendet. Pod-Suffixe und die ClusterIP des Dienstes unterscheiden sich in Ihrer Umgebung.
MCP-Pods (standardmäßig zwei; automatisches Skalieren auf zehn unter Last):
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
In der Spalte READY muss für jeden Pod 2/2 angezeigt werden. Die beiden Container in jedem Pod sind:
apigee-mcp-server: der MCP-Datenebenencontainer, mit dem MP-Pods verbunden werden.apigee-mcp-server-config: Der Konfigurations-Sidecar (ein Modus des Binärprogrammsapigee-watcher), der Konfigurations-Bundles von der Apigee-Steuerungsebene abruft und in ein freigegebenes Volume schreibt, das vom MCP-Datenebenencontainer gelesen wird.
MCP ApigeeDeployment (eine benutzerdefinierte Kubernetes-Ressource, keine Vanilla-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
Der erwartete Status ist running. Prüfen Sie auch, ob der zugrunde liegende Pod 2/2
Running ist:
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-Dienst:
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
Prüfen Sie, ob MINPODS mit mcpServer.replicaCountMin aus Ihrer overrides.yaml (Standard 2) und MAXPODS mit mcpServer.replicaCountMax (Standard 10) übereinstimmt. Die Spalten TARGETS, REPLICAS und AGE hängen von Live-Messwerten und dem Clusterstatus ab.
Prüfen, ob die Message Processor-Pods den Eintrag hostAliases erhalten haben
In jedem MP-Pod muss der eingefügte Eintrag vorhanden sein. Wenn auch nur ein Pod fehlt, kann dieser Pod keine MCP-Toolaufrufe weiterleiten. Listen Sie alle MP-Pods und ihre hostAliases auf:
kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
Erwartete Ausgabe: Jeder MP-Pod listet ein hostAliases-Array mit einem Eintrag mit zwei Hostnamen auf, die auf die MCP-Dienst-ClusterIP aus dem vorherigen Schritt verweisen (der zweite Hostname verwendet den Namen Ihrer Organisation in Kleinbuchstaben). Die Namen der Message Processor-Pods folgen der Vorlage apigee-runtime-TRUNCATED_ORG-ENV_GROUP_HASH-REV-POD_HASH, wobei TRUNCATED_ORG der Name Ihrer Organisation ist (gekürzt, um die Kubernetes-Namensbeschränkung von 63 Zeichen einzuhalten, wenn der Name Ihrer Organisation lang ist), ENV_GROUP_HASH ein umgebungsspezifischer Hash der Bereitstellungsgruppe ist, REV die aktuelle Versionsnummer der Release-Version ist (vier Ziffern, z. B. 1170) und POD_HASH ein zufälliges Suffix pro Pod ist. Beispiel:
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]]
Wenn ein Pod einen leeren hostAliases-Wert aufweist, hat der Message Processor ApigeeDeployment die aktualisierte Pod-Spezifikation nicht vollständig übernommen. Erzwingen Sie ein neues gestaffeltes Canary-Release, indem Sie die aktuellen Message Processor-Pods löschen. Der ApigeeDeployment-Controller rendert sie dann aus der aktuellen Spezifikation neu, die jetzt den hostAliases-Eintrag enthält:
kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime
Der ApigeeDeployment-Controller erstellt die Pods innerhalb einer Minute neu. Beachten Sie, dass kubectl rollout restart deploy (der Vanilla-Kubernetes-Befehl) nicht auf dem Message Processor funktioniert, da der Message Processor als benutzerdefinierte ApigeeDeployment-Ressource und nicht als Deployment bereitgestellt wird.
Installation abgeschlossen
Zusammen bestätigen die vorherigen drei Prüfungen, dass die MCP-Datenebene ausgeführt wird und über MP adressierbar ist:
- Jeder MCP-Pod ist
2/2 Running. Der MCP-Datenebenencontainer besteht die Kubernetes-Bereitschaftsprüfung auf Port15021nicht, wenn das vom Operator ausgestellte TLS-Zertifikat nicht geladen ist und der Sidecar seine anfängliche MCP-Konfiguration noch nicht geladen hat. Daher erfüllenReady-Pods beide Voraussetzungen. - Die Spezifikation jedes MP-Pods enthält den Eintrag
hostAliases, dermcp.apigee.internalundORG_NAME.mcp.apigee.internalan die ClusterIP des MCP-Dienstes anpinnt. MP-Pods können daher MCP-Proxy-Zielendpunkte in Ihre clusterinterne MCP-Datenebene auflösen. - Ein MP-Pod löst
mcp.apigee.internalüber den eingefügtenhostAliases-Eintrag in die ClusterIP des MCP-Dienstes auf.
Sie überprüfen den End-to-End-MCP-Tool-Traffic (einen tatsächlichen MCP-initialize- oder tools/list-Aufruf über Ihren Apigee-Ingress) im Rahmen des freigegebenen MCP-Schnellstarts, nachdem Sie Ihren ersten MCP-Discovery-Proxy bereitgestellt haben.
Wenn eine der vorherigen drei Prüfungen fehlschlägt, lesen Sie den Abschnitt Fehlerbehebung bei MCP-Bereitstellungen, bevor Sie mit der Kurzanleitung fortfahren.
Schritt 6: MCP auf den verbleibenden Clustern aktivieren
MCP-Anfragen für einen bestimmten Hostnamen können an jeden Cluster weitergeleitet werden, der die entsprechende Apigee-Umgebungsgruppe bedient. Wenn MCP in einigen Clustern aktiviert ist und in anderen in derselben Umgebungsgruppe nicht, schlagen MCP-Anfragen fehl, die an einen Cluster ohne MCP weitergeleitet werden (werden in der Regel als 503 Service Unavailable an den Client zurückgegeben).
Aktivieren Sie MCP einheitlich für jeden Cluster, der dieselbe Umgebungsgruppe bedient. Wiederholen Sie die Schritte 1, 3, 4 und 5 für jeden weiteren Cluster. Sie müssen Schritt 2 (Watcher-Identität Zugriff gewähren) nicht wiederholen. Diese Berechtigung gilt für die Apigee-Organisation und alle Cluster in derselben Organisation.
Zustandsloses MCP-Protokoll (Version 1.17.4 und höher) überprüfen
Apigee Hybrid-Versionen ab 1.17.4 stellen standardmäßig das zustandslose MCP-Protokoll (Version 2026-07-28) bereit. Rufen Sie die Methode server/discover auf, die nur im zustandslosen Protokoll vorhanden ist, um zu prüfen, ob Ihre Installation das zustandslose Protokoll unterstützt. Für diese Prüfung ist ein bereitgestellter MCP-Discovery-Proxy erforderlich. Führen Sie sie daher nach Abschluss der MCP-Kurzanleitung aus.
Überspringen Sie diese Prüfung bei den Versionen 1.17.0 bis 1.17.3, die nur die zustandsorientierten MCP-Protokollversionen bereitstellen.
Die Anfrage wird an einen Hostnamen in Ihrer Apigee-Umgebungsgruppe gesendet, sodass jeder Cluster, der die Umgebungsgruppe bedient, sie beantworten kann. Bei der Prüfung wird daher die Umgebungsgruppe und nicht ein bestimmter Cluster überprüft. Sie müssen sie nur einmal pro Umgebungsgruppe ausführen. Verwenden Sie die clusterspezifischen Prüfungen in Schritt 5: Installation prüfen, um zu bestätigen, dass jeder Cluster fehlerfrei ist.
curl -X POST "https://MCP_ENDPOINT_URL/mcp" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "MCP-Protocol-Version: 2026-07-28" \ -H "Mcp-Method: server/discover" \ -H "Authorization: Bearer TOKEN" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } }'
Ersetzen Sie Folgendes:
MCP_ENDPOINT_URL: Der Hostname Ihres MCP-Endpunkts. Dies ist ein Hostname, der in Ihrer Apigee-Umgebungsgruppe registriert ist und von Ihrem Apigee-Ingress-Gateway bereitgestellt wird. Beispiel:api.example.com.TOKEN: Ein OAuth 2.0-Zugriffstoken, das erforderlich ist, wenn Ihr MCP-Proxy Tokens mit einer OAuthV2-Richtlinie verifiziert. Wenn der Proxy stattdessen eine VerifyAPIKey-Richtlinie verwendet, ersetzen Sie die Zeile-H "Authorization: Bearer TOKEN"durch den API-Schlüssel im Header oder Suchparameter, den die Richtlinie liest. Wenn der Proxy nicht authentifizierte Anfragen akzeptiert, entfernen Sie die Zeile.
Die Umgebungsgruppe stellt das zustandslose MCP-Protokoll bereit, wenn die Antwort HTTP 200 ist und das Array result.supportedVersions den Wert 2026-07-28 enthält. Eine erfolgreiche Antwort sieht in etwa so aus:
{ "id": 1, "jsonrpc": "2.0", "result": { "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "SERVICE_NAME", "version": "1.0.0" } }, "cacheScope": "public", "capabilities": { "tools": { "listChanged": false } }, "resultType": "complete", "supportedVersions": [ "2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" ], "ttlMs": 0 } }
In der Antwort ist SERVICE_NAME der Name des MCP-Dienstes, der geantwortet hat. Die Felder cacheScope und ttlMs sind Cache-Hinweise. "ttlMs": 0 ist der Standardwert und weist nicht auf einen Fehler hin.
Wenn die Antwort ein Fehler ist, können Sie damit die Ursache ermitteln:
- HTTP
400miterror.code-32602underror.messageUnsupported protocol version: Auf den Clustern werden die Apigee Hybrid-Versionen1.17.0bis1.17.3ausgeführt, die das zustandslose Protokoll nicht unterstützen. Führen Sie ein Upgrade auf Version1.17.4oder höher durch. - Alle anderen Fehler, z. B. HTTP
401oder403(Authentifizierung), HTTP404(kein MCP-Proxy unter/mcpin dieser Umgebungsgruppe bereitgestellt), HTTP503(fehlerhafte MCP-Datenebene) oder ein anderererror.code-Wert aus einer fehlerhaften Anfrage: Die Ursache ist nicht die Apigee Hybrid-Version. Weitere Informationen finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen.
Eine vollständige Liste der Anforderungen und Fehler für zustandslose Anfragen finden Sie unter Unterstützte MCP-Protokollversionen.
Rollback
Wenn Sie MCP in einem Cluster deaktivieren möchten, legen Sie enableMcpServer: false fest (oder entfernen Sie das Feld vollständig) in overrides.yaml und aktualisieren Sie dann das apigee-org-Diagramm:
helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ \ --namespace APIGEE_NAMESPACE --atomic -f overrides.yaml
Das Feld enableMcpServer wird nur vom Diagramm apigee-org verwendet. Daher muss das Operatordiagramm während einer Deaktivierung nicht aktualisiert werden. Der Apigee-Operator (unverändert) übernimmt die Konfigurationsänderung aus der benutzerdefinierten Ressource ApigeeOrganization, löscht die MCP-Ressourcen und entfernt den Eintrag hostAliases aus der Message Processor-Pod-Spezifikation, was eine Freigabe des apigee-runtime ApigeeDeployment auslöst. Rollback in einem genehmigten Wartungsfenster durchführen.
Nach dem Rollback sind die MCP-Discovery-Proxys, die Sie in der Apigee-Umgebung bereitgestellt haben, weiterhin in der Apigee-Steuerungsebene vorhanden. Es gibt jedoch keinen Cluster in dieser Umgebungsgruppe, der MCP-Traffic verarbeitet. Heben Sie die Bereitstellung der MCP-Discovery-Proxys auf, um die Funktion vollständig zu deaktivieren, oder lassen Sie sie bereitgestellt und aktivieren Sie MCP später wieder auf den Clustern.
mTLS zwischen der MCP-Datenebene und dem Ingress-Gateway konfigurieren
MCP-Toolaufrufe verlassen die MCP-Datenebene und gelangen über das Apigee-Ingress-Gateway wieder in Ihren Cluster. Dabei werden dieselben Host-Aliasse und derselbe virtualhosts[]-Eintrag wie bei jedem anderen API-Aufruf an diese Umgebungsgruppe verwendet. Standardmäßig stellt die MCP-Datenebene eine Verbindung zum Ingress-Gateway über einseitiges TLS her: Die Verbindung ist verschlüsselt, aber die MCP-Datenebene stellt kein Clientzertifikat bereit und prüft das Zertifikat des Ingress-Gateways nicht.
Ab Apigee Hybrid 1.17.4 können Sie mit dem Block virtualhosts[].mcpMtls gegenseitiges TLS (mTLS) für diese Verbindung pro Umgebungsgruppe aktivieren. Wenn mTLS aktiviert ist:
- Die MCP-Datenebene stellt ein von Ihnen ausgestelltes Clientzertifikat bereit. Das Ingress-Gateway authentifiziert die MCP-Datenebene also auf dieselbe Weise wie jeden anderen mTLS-Client dieser Umgebungsgruppe.
- Die MCP-Datenebene prüft, ob das Zertifikat des Ingress-Gateways mit einer von Ihnen angegebenen Zertifizierungsstelle verknüpft ist und ob es den aufgerufenen Host-Alias abdeckt. Beide Prüfungen sind standardmäßig aktiviert und können pro Umgebungsgruppe deaktiviert werden.
Sie konfigurieren mTLS für jeweils eine Umgebungsgruppe. Umgebungsgruppen ohne mcpMtls verwenden weiterhin One-Way-TLS, einschließlich Umgebungsgruppen, die vom selben Ingress-Gateway bereitgestellt werden. So können Sie schrittweise migrieren. Das Clientzertifikat und die vertrauenswürdige Zertifizierungsstelle sind ebenfalls pro Umgebungsgruppe vorhanden: Es gibt kein clusterweites MCP-Clientzertifikat und zwei Umgebungsgruppen auf demselben Ingress-Gateway können unterschiedliche Clientzertifikate präsentieren, die von verschiedenen Zertifizierungsstellen ausgestellt wurden.
In den mcpMtls-Feldern werden absichtlich die Namen der TLS-Felder für eingehenden Traffic eine Ebene höher wiederverwendet. Die Rollen sind jedoch umgekehrt, da auf dieser Verbindung die MCP-Datenebene der Client und das Ingress-Gateway der Server ist:
| Feld | Unter virtualhosts[].mcpMtls |
Direkt unter virtualhosts[] |
|---|---|---|
sslCertPath, sslKeyPath |
Das Clientzertifikat und der Schlüssel, die die MCP-Datenebene dem Ingress-Gateway präsentiert.
Muss die erweiterte Schlüsselverwendung clientAuth enthalten. |
Das eigene Serverzertifikat und der Schlüssel des Ingress-Gateways. |
sslSecret |
Secret, das dieses Clientzertifikat und diesen Schlüssel enthält (Schlüssel cert, key). |
Secret, das das Serverzertifikat und den Schlüssel des Ingress-Gateways enthält. |
caCertPath oder der sslSecret-Name mit angehängtem -cacert |
Die Zertifizierungsstelle, der die MCP-Datenebene für das Serverzertifikat des Ingress-Gateways vertraut. | Die Zertifizierungsstelle, der das Ingress-Gateway für eingehende Clientzertifikate vertraut, einschließlich der Zertifikate der MCP-Datenebene. |
Hinweis
- Auf dem Cluster wird Apigee Hybrid
1.17.4oder höher ausgeführt. Die Diagrammeapigee-operator,apigee-orgundapigee-virtualhostwurden alle auf diese Version aktualisiert und MCP wurde aktiviert. Führen Sie dazu die Schritte aus, die mit Schritt 1:overrides.yamlbearbeiten beginnen. Achten Sie darauf, dass das Upgrade den Schritt Aktualisierte Apigee-CRDs installieren (kubectl apply -k apigee-operator/etc/crds/default/ ...) umfasst. Durch ein Upgrade des Operator-Diagramms allein werden die CRDs nicht aktualisiert. Bei CRDs, die älter als1.17.4sind, wird der BlockmcpMtlsvom API-Server automatisch aus der RessourceApigeeRouteConfigentfernt. Der Block hat also keine Auswirkungen und der Cluster kann die unter Prüfen beschriebenen Zertifikatsprobleme nicht melden. - Ein Clientzertifikat und ein privater Schlüssel für die MCP-Datenebene, ausgestellt von einer Zertifizierungsstelle, der das Ingress-Gateway für diese Umgebungsgruppe vertraut: die Zertifizierungsstelle in
virtualhosts[].caCertPathoder das SecretINGRESS_SECRET_NAME-cacertdesselbenvirtualhosts[]-Eintrags. Wenn das Zertifikat eine Erweiterung für die erweiterte Schlüsselverwendung hat, muss esclientAuthenthalten. Die MCP-Datenebene lehnt ein Zertifikat ab, dessen erweiterte Schlüsselverwendung es weglässt (ein Zertifikat ohne Erweiterung für die erweiterte Schlüsselverwendung wird akzeptiert). Verwenden Sie eine private Zertifizierungsstelle: Öffentliche Zertifizierungsstellen stellen in der Regel keine Zertifikate mit der erweiterten SchlüsselverwendungclientAuthaus. - Das CA-Zertifikat, das das eigene TLS-Zertifikat des Ingress-Gateways für diese Umgebungsgruppe signiert hat (das Zertifikat in
virtualhosts[].sslCertPathoderINGRESS_SECRET_NAME). Die MCP-Datenebene validiert das Ingress-Gateway anhand dieser CA. Lassen Sie es nur weg, wenn SiedisableChainValidation: truefestlegen. - Wenn Sie
disableSanValidation: truenicht festlegen, müssen im Zertifikat des Ingress-Gateways die Host-Aliasse der Umgebungsgruppe in den alternativen Antragstellernamen aufgeführt sein. Normalerweise ist das der Fall, da externe Clients dieselbe Prüfung durchführen.
Wählen Sie eine der beiden Möglichkeiten aus, um die Zertifikate bereitzustellen. Sie spiegeln die beiden Optionen für die mTLS-Konfiguration des Ingress-Gateways wider.
Option 1: Zertifikatsdateien
Fügen Sie mcpMtls mit Dateipfaden zum Eintrag virtualhosts[] der Umgebungsgruppe hinzu. Helm kann nur Dateien im Diagrammverzeichnis lesen. Die Dateien müssen sich also unter $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/ befinden (z. B. im Verzeichnis certs/, neben Ihren Ingress-Zertifikaten). Die Pfade sind relativ zu diesem Verzeichnis, genau wie die vorhandenen Felder sslCertPath, sslKeyPath und caCertPath. Weitere Informationen finden Sie unter TLS-Zertifikate erstellen.
virtualhosts: - name: ENV_GROUP_NAME tlsMode: MUTUAL caCertPath: certs/INGRESS_CA_FILE # CA the ingress gateway trusts for client certificates sslCertPath: certs/INGRESS_CERT_FILE sslKeyPath: certs/INGRESS_KEY_FILE mcpMtls: sslCertPath: certs/MCP_CLIENT_CERT_FILE # client certificate the MCP data plane presents sslKeyPath: certs/MCP_CLIENT_KEY_FILE caCertPath: certs/MCP_TRUST_CA_FILE # CA that signed INGRESS_CERT_FILE
Option 2: Kubernetes-Secrets
- Erstellen Sie ein Secret mit dem Clientzertifikat und dem Schlüssel. Die Datenschlüssel müssen
certundkeysein:kubectl create secret generic MCP_CLIENT_SECRET_NAME -n APIGEE_NAMESPACE \ --from-file=cert=MCP_CLIENT_CERT_FILE \ --from-file=key=MCP_CLIENT_KEY_FILE
- Erstellen Sie ein zweites Secret mit der Zertifizierungsstelle, die das Zertifikat des Ingress-Gateways signiert hat.
Der Name muss der Name des ersten Secrets mit dem Suffix
-cacertsein und der Datenschlüssel musscacertsein. Überspringen Sie diesen Schritt nur, wenn SiedisableChainValidation: truefestgelegt haben:kubectl create secret generic MCP_CLIENT_SECRET_NAME-cacert -n APIGEE_NAMESPACE \ --from-file=cacert=MCP_TRUST_CA_FILE
- Verweisen Sie auf das erste Secret aus dem Eintrag
virtualhosts[]der Umgebungsgruppe:virtualhosts: - name: ENV_GROUP_NAME tlsMode: MUTUAL sslSecret: INGRESS_SECRET_NAME mcpMtls: sslSecret: MCP_CLIENT_SECRET_NAME
Kombinieren Sie die beiden Optionen nicht in einem mcpMtls-Block. helm upgrade
schlägt schnell mit einer Diagnose fehl, die den Eintrag für häufige Fehlkonfigurationen benennt, darunter:
sslSecret kombiniert mit einem Pfadfeld; sslCertPath ohne
sslKeyPath oder sslKeyPath ohne sslCertPath;
keine der beiden Formen angegeben; oder ein referenziertes Secret, das fehlt oder nicht die erwarteten Datenschlüssel enthält. Andere Inkonsistenzen (z. B. caCertPath zusammen mit disableChainValidation: true) werden in der virtualhosts[].mcpMtls-Attributreferenz beschrieben.
Änderung anwenden
Aktualisieren Sie den Release apigee-virtualhost für die Umgebungsgruppe:
helm upgrade ENV_GROUP_NAME apigee-virtualhost/ \ --namespace APIGEE_NAMESPACE \ --set envgroup=ENV_GROUP_NAME \ -f overrides.yaml
Es werden keine MCP-Pods neu gestartet und keine andere Umgebungsgruppe ist betroffen. Die MCP-Datenebene übernimmt die neue Konfiguration bei der nächsten regelmäßigen Aktualisierung, in der Regel innerhalb weniger Minuten.
Wenn Sie den Eintrag im selben Upgrade von tlsMode: SIMPLE auf MUTUAL umstellen, können MCP-Toolaufrufe an diese Umgebungsgruppe während dieses Zeitfensters fehlschlagen, da das Ingress-Gateway ein Clientzertifikat anfordert, bevor die MCP-Datenebene eines präsentiert. Nehmen Sie die Änderung in einem Wartungsfenster für diese Umgebungsgruppe vor.
Bestätigen
- Prüfen Sie, ob die Konfiguration die Routingressource der MCP-Datenebene für die Umgebungsgruppe erreicht hat. In der Ausgabe müssen der Secret-Name und die beiden von Ihnen konfigurierten Validierungs-Flags angezeigt werden (nicht festgelegte Flags werden weggelassen):
Wenn die Spaltekubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
mcpMtlseinige Minuten nach dem Upgrade immer noch leer ist, liegt das in der Regel daran, dass die Apigee-CRDs im Cluster älter als1.17.4sind und das Feld gelöscht haben: Wenden Sie die aktualisierten CRDs an (siehe Vorbereitung) und führen Sie dasapigee-virtualhost-Upgrade noch einmal aus. Seltener wurde dasapigee-org-Diagramm (das das Watcher-Image bereitstellt) nicht auf1.17.4aktualisiert. - Prüfen Sie, ob die MCP-Datenebene die Zertifikate akzeptiert hat. Der Sidecar protokolliert eine
error-Zeile und behält die vorherige Konfiguration für diese Umgebungsgruppe bei, wenn ein Secret fehlt, nicht lesbar ist oder unbrauchbares Material enthält. Unmittelbar nach der Aktivierung sollten keine vorhanden sein: Suchen Sie im gesamten Log und nicht nur in einem aktuellen Fenster: Ein fehlerhaftes Secret wird gemeldet, wenn der Sidecar es zum ersten Mal sieht, nicht bei jeder Aktualisierung.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
- Prüfen Sie, ob Zertifikatsprobleme als
ApigeeIssue-Ressourcen gemeldet wurden (siehe MCP-mTLS-Probleme):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)'
- Senden Sie eine MCP-Anfrage über einen bereitgestellten MCP-Discovery-Proxy in der Umgebungsgruppe, wie in der MCP-Kurzanleitung beschrieben. Ein erfolgreicher Toolaufruf bestätigt den vollständigen Pfad, einschließlich des mTLS-Handshakes mit dem Ingress-Gateway.
Zertifikate rotieren
- Option 2 (Secrets): Aktualisieren Sie die Secrets direkt, z. B. mit
kubectl create secret generic ... --dry-run=client -o yaml | kubectl apply -f -. Die MCP-Datenebene überwacht beide Secrets und lädt das neue Material bei der nächsten Aktualisierung. Es ist kein Pod-Neustart und keinhelm upgradeerforderlich und laufende MCP-Aufrufe werden nicht unterbrochen. Lassen Sie die Datenschlüsselcert,keyundcacertunverändert. - Option 1 (Dateien): Ersetzen Sie die Dateien und führen Sie denselben
helm upgrade-Befehl wie unter Änderung anwenden aus. Das Diagramm aktualisiert die von ihm verwalteten Secrets und die MCP-Datenebene übernimmt sie wie für Option 2 beschrieben.
14 Tage vor Ablauf des Clientzertifikats oder der Vertrauens-Zertifizierungsstelle löst der Cluster einen ApigeeIssue mit dem Schweregrad WARNING aus. Nach Ablauf wird der Schweregrad ERROR verwendet. Ein abgelaufenes Zertifikat wird weiterhin angezeigt, bis Sie es ersetzen. Das Ingress-Gateway lehnt dann den Handshake ab.
mTLS für eine Umgebungsgruppe deaktivieren
Entfernen Sie den Block mcpMtls, setzen Sie den tlsMode des Eintrags im selben Bearbeitungsschritt auf SIMPLE zurück (oder entfernen Sie tlsMode) und führen Sie denselben helm upgrade aus. Die MCP-Datenebene setzt diese Umgebungsgruppe bei der nächsten Aktualisierung auf One-Way-TLS zurück und entfernt das Zertifikatsmaterial, das sie für die Gruppe geschrieben hat.
Secrets, die Sie manuell für Option 2 erstellt haben, werden nicht gelöscht. Entfernen Sie sie selbst, wenn sie nicht mehr benötigt werden.
Verhalten, wenn Zertifikate nicht verfügbar sind
Wenn die MCP-Datenebene die konfigurierten Zertifikate für eine Umgebungsgruppe nicht lesen oder verwenden kann (ein Secret fehlt, ein Datenschlüssel fehlt, dem Zertifikat fehlt clientAuth oder das CA-Secret ist keine CA), wird eine error-Zeile protokolliert, die Umgebungsgruppe wird weiterhin mit den letzten erfolgreich geladenen Zertifikaten bedient und es wird bei späteren Aktualisierungen noch einmal versucht. Wenn für die Gruppe noch nie Zertifikate geladen wurden, schlagen MCP-Toolaufrufe an diese Gruppe fehl (der Client empfängt in der Regel 503 Service Unavailable), während alle anderen Umgebungsgruppen weiterhin bedient werden. Korrigieren Sie das Secret oder den overrides.yaml-Eintrag. Ein Neustart ist nicht erforderlich. Die entsprechenden Meldungen finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen.
Referenz: MCP-Felder in overrides.yaml
In der folgenden Tabelle sind alle Apigee Hybrid-overrides.yaml-Felder aufgeführt, die das MCP-Verhalten in Version 1.17.0 steuern. Nur enableMcpServer ist erforderlich. Alle anderen Felder haben sichere Standardwerte, die für die meisten Installationen geeignet sind.
Die Felddefinitionen entsprechen den Standardwerten des Helm-Diagramms apigee-org für Apigee Hybrid 1.17.0. Die mTLS-Einstellungen für die Verbindung von der MCP-Datenebene zum Ingress-Gateway sind nicht in dieser Tabelle enthalten: Sie sind pro Umgebungsgruppe unter virtualhosts[].mcpMtls im apigee-virtualhost-Diagramm (1.17.4 und höher) aufgeführt.
| Feld | Typ | Standard | Empfohlene Feinabstimmung |
|---|---|---|---|
enableMcpServer |
boolean | false |
Erforderlich. Legen Sie true fest, um MCP für diesen Cluster zu aktivieren. Wenn Sie dieses Feld aktivieren, wird ein gestaffeltes Canary-Release des Message Processor ausgelöst. Aktivieren Sie die Option nur in einem Wartungsfenster und warten Sie, bis die Veröffentlichung abgeschlossen ist, bevor Sie fortfahren. |
mcpServer.replicaCountMin |
integer | 2 |
Behalte 2 für HA bei. Erhöhen Sie den Wert nur, wenn Sie eine Baseline mit hohem MCP-Traffic haben. Der HPA skaliert automatisch hoch, wenn die CPU-Auslastung hoch ist. Signal: anhaltende HPA bei replicaCountMax und CPU über dem Zielwert. |
mcpServer.replicaCountMax |
integer | 10 |
Erhöhen Sie den Wert, wenn Sie feststellen, dass der HPA während der Spitzenzeiten auf 10 begrenzt ist. Signal:
kubectl top pods -l app=apigee-mcp-server zeigt alle Pods an, die sich zu Spitzenzeiten nahe ihrem CPU-Limit befinden. Wenn metrics-server nicht installiert ist, verwenden Sie kubectl get hpa -n APIGEE_NAMESPACE | grep apigee-mcp-server und prüfen Sie, ob die Spalte REPLICAS die Obergrenze MAXPODS erreicht hat. |
mcpServer.targetCPUUtilizationPercentage |
integer | 70 |
Senken Sie den Wert für latenzempfindliche Arbeitslasten auf 50–60 (frühere Skalierung). Erhöhen Sie den Wert auf 80–85, um die Anzahl der Replikate in kostenempfindlichen Clustern zu reduzieren. Signal: Die P95-Anfragelatenz korreliert mit der CPU pro Pod. |
mcpServer.resources.requests |
ResourceList | cpu: 500m, memory: 512Mi |
Erhöhen Sie die Anfragen, wenn Pods im stabilen Zustand häufig OOMKilled oder CPU-gedrosselt werden. Signal: kubectl describe pod zeigt OOMKilled- oder gedrosselte Bedingungen an. |
mcpServer.resources.limits |
ResourceList | cpu: 2000m, memory: 1Gi |
Erhöhen Sie das CPU-Limit, bevor Sie die Anzahl der Replikate erhöhen, wenn die p95-Latenz hoch, aber die Gesamtzahl der Abfragen pro Sekunde niedrig ist (wenige, teure Anfragen). Erhöhen Sie das Speicherlimit nur, wenn OOMKills angezeigt werden. |
mcpServer.sidecar.resources.requests |
ResourceList | cpu: 200m, memory: 128Mi |
Muss selten optimiert werden. Der Sidecar erstellt und schreibt regelmäßig Konfigurations-Bundles. Die CPU-Auslastung im stabilen Zustand ist minimal. |
mcpServer.sidecar.resources.limits |
ResourceList | cpu: 500m, memory: 512Mi |
Muss selten optimiert werden. Erhöhen Sie den Arbeitsspeicher nur, wenn Sie eine ungewöhnlich große Anzahl von MCP-Tools in einem einzelnen Discovery-Proxy bereitstellen. |
mcpServer.terminationGracePeriodSeconds |
integer | 30 |
Muss selten optimiert werden. Erhöhen Sie den Wert, wenn langlebige, aktive MCP-Anfragen während eines Pod-Drains mehr Zeit benötigen. |
mcpServer.annotations |
Karte | {} |
Fügen Sie zusätzliche Pod-Annotationen hinzu, wenn Ihr Cluster diese benötigt. |
mcpServer.serviceAccountPath |
String | unset | Lassen Sie die Einstellung deaktiviert, es sei denn, Sie benötigen eine Identitätstrennung pro Komponente. Wenn nichts festgelegt ist, verwendet MCP watcher.serviceAccountPath. MCP verwendet envs[].serviceAccountPaths.runtime nicht. Die apigee-watcher-Identität hat bereits die Berechtigungen, die der MCP-Sidecar benötigt. Wenn Sie dieses Feld überschreiben, geben Sie den Pfad zu einer JSON-Datei mit dem Dienstkontoschlüssel für Google Cloud an. Schließt sich gegenseitig mit mcpServer.gsa aus.
Wenn Workload Identity nicht aktiviert ist und Sie weder mcpServer.serviceAccountRef noch serviceAccountSecretProviderClass festlegen, müssen Sie mcpServer.serviceAccountPath oder watcher.serviceAccountPath festlegen. Wenn Sie keines von beiden festlegen, schlägt helm upgrade mit dem Fehler mcpServer.serviceAccountPath or watcher.serviceAccountPath is
required!! fehl.
Nach Möglichkeit Workload Identity (GKE) oder Workload Identity Federation (AKS/EKS) verwenden. Dateibasierte Dienstkontoschlüssel müssen rotiert, sicher gespeichert und an jeden Cluster verteilt werden. Sie sind die häufigste Quelle für Lecks in Supportartefakten (siehe Supportfälle). |
mcpServer.gsa |
String | unset | Lassen Sie die Einstellung deaktiviert, es sei denn, Sie benötigen eine Identitätstrennung pro Komponente. Wenn nicht festgelegt, greift MCP auf watcher.gsa und dann auf gcp.workloadIdentity.gsa zurück. Die Identität apigee-watcher hat bereits die Berechtigungen, die der MCP-Sidecar benötigt. Daher wird empfohlen, sie wiederzuverwenden. Überschreiben Sie dies nur dann mit der E-Mail-Adresse eines dedizierten Google Cloud-Dienstkontos, wenn Ihre Organisation aus Prüfungsgründen eine separate Identität für den MCP-Sidecar benötigt. |
mcpServer.serviceAccountRef |
String | unset | Erweitert. Name eines vorhandenen Kubernetes-Secrets im Apigee-Namespace, das einen Google Cloud-Dienstkontoschlüssel für den MCP-Sidecar enthält. Verwenden Sie diese Option nur, wenn Sie Secrets für Dienstkontoschlüssel außerhalb der Apigee Helm-Diagramme verwalten. Schließt sich mit mcpServer.serviceAccountPath und mcpServer.gsa gegenseitig aus.
MCP verwendet watcher.serviceAccountRef nicht. Wenn in Ihrer Basisinstallation der Schlüssel apigee-watcher in einem Kubernetes-Secret mit watcher.serviceAccountRef gespeichert wird, legen Sie für dieses Attribut denselben Secret-Namen fest. |
mcpServer.podDisruptionBudget |
Karte | unset | Optionales PodDisruptionBudget für die MCP-Pods. Akzeptiert minAvailable oder maxUnavailable (Ganzzahl oder Prozentstring). Legen Sie nur einen der beiden fest. Lassen Sie diese Option deaktiviert, es sei denn, Ihr Cluster hat strenge Richtlinien für freiwillige Unterbrechungen, die ein explizites Budget erfordern. |
mcpServer.tolerations |
list | nicht festgelegt (Fallback auf tolerations auf oberster Ebene) |
Standard-Kubernetes-Toleranzen für MCP-Pods. Legen Sie dies nur fest, wenn MCP-Pods Markierungen tolerieren müssen, die andere Apigee-Komponenten nicht tolerieren. |
mcpServer.image.pullPolicy |
String | IfNotPresent |
Image-Pull-Richtlinie für den MCP-Servercontainer. Wird selten geändert. |
mcpServer.sidecar.image.pullPolicy |
String | IfNotPresent |
Image-Pull-Richtlinie für den MCP-Sidecar-Container. Wird selten geändert. |
MCP-Tool-Kapazität schätzen
Apigee Hybrid erzwingt keine feste maximale Anzahl von MCP-Tools pro Organisation. Stattdessen ist die Toolkapazität durch vier feste Größenlimits begrenzt, die bei der Bereitstellung oder Anfrage erzwungen werden. Ob eine bestimmte Anzahl von Tools passt, hängt von der Größe der einzelnen Tools ab, die sich aus der OpenAPI-Spezifikation ergibt, die das Tool definiert.
Durchschnittliche Kapazität
Bei den meisten OpenAPI-Spezifikationen – einer Mischung aus Tools mit unterschiedlicher Parameteranzahl, Anfragetextgröße und Beschreibungslänge, wobei die meisten Tools im kleinen bis mittleren Größenbereich liegen – können Sie in der Regel davon ausgehen, dass 10.000 MCP-Tools pro Organisation in das standardmäßige Antwortgrößenlimit von tools/list passen.
Die tatsächliche Kapazität hängt von der spezifischen Form Ihrer OpenAPI-Spezifikation ab. In Organisationen, deren Spezifikationen von Tools mit vielen Parametern, großen Anfragetexten oder langen Beschreibungen dominiert werden, passen proportional weniger Tools, bevor eines der vier unten aufgeführten harten Limits erreicht wird. Wenn Sie die Kapazität für Ihre spezifischen Spezifikationen prüfen möchten, folgen Sie der Anleitung unter Kapazität für Ihre Spezifikation schätzen.
Harte Limits
In der Apigee Hybrid-Version 1.17.0 gelten vier Größenbeschränkungen. Das niedrigste anwendbare Limit ist verbindlich. Wenn Sie ein Limit erhöhen, werden die anderen nicht erhöht.
| Limit | Wert | Umfang | Fehlermodus |
|---|---|---|---|
| Größe der OpenAPI-Spezifikationsdatei | 3 MiB | pro .yaml-Datei |
400 bei Proxy-Validierung |
| Größe des MCP-Proxy-Bundles (dekomprimiert) | 50 MiB | pro MCP-Erkennungsproxy | 400 bei Proxy-Validierung |
tools/list-Antwortgröße |
10 MiB (Standard) | pro Hostname | 502 mit TooBigBody |
| Hostnamen pro Umgebungsgruppe | 100 | pro Umgebungsgruppe | 400 bei der Aktualisierung der Umgebungsgruppe |
Was bestimmt die Größe pro Tool?
Die Größe pro Tool setzt sich fast vollständig aus dem inputSchema des Tools zusammen, das aus den parameters und requestBody der OpenAPI-Spezifikation für den Vorgang abgeleitet wird.
Drei Eigenschaften sind am wichtigsten:
- Anzahl der Parameter. Jeder Parametereintrag trägt etwa 100 Byte zur Größe des Tools in der
tools/list-Antwort bei. - Anzahl der Attribute im Anfragetext. Jedes Attribut im Anfragetext trägt etwa 100 Byte bei. Vorgänge mit einem Anfragetext (normalerweise
POSTundPUT) sind daher wesentlich größer als Vorgänge ohne Anfragetext (normalerweiseGETundDELETE). - Länge der Beschreibung: Vorgangsbeschreibungen werden fast wörtlich in das Tool kopiert. Eine längere Beschreibung erhöht also direkt die Größe des Tools.
Antwortschemas werden nicht auf das Größenbudget angerechnet. Nur parameters und requestBody erreichen die MCP-Konfiguration. Wenn die Kapazität nur anhand der OpenAPI-Dateigröße bemessen wird, werden die Kosten daher tendenziell überschätzt, da die meisten echten OpenAPI-Spezifikationen Antwortschemadefinitionen enthalten, die sich nicht auf die Toolgröße auswirken.
Kapazität für Ihre Spezifikation schätzen
Die zuverlässigste Methode, um die Toolkapazität für Ihre OpenAPI-Spezifikationen zu schätzen, besteht darin, eine repräsentative Teilmenge zu messen:
- Stellen Sie einen MCP-Discovery-Proxy bereit, der auf eine kleine, repräsentative Teilmenge der Tools verweist, die Sie veröffentlichen möchten (z. B. 50 bis 100 Tools, die die Mischung aus Parameteranzahl, Anfragetextgrößen und Beschreibungslängen in Ihrer vollständigen Spezifikation widerspiegeln).
- Rufen Sie
tools/listfür den bereitgestellten Proxy auf und erfassen Sie die Antwortgröße in Byte und die Anzahl der zurückgegebenen Tools. - Teilen Sie die Antwortgröße durch die Anzahl der Tools, um die durchschnittliche Größe pro Tool für Ihre Spezifikation zu erhalten.
- Teilen Sie das anwendbare Limit für die Antwortgröße von
tools/list(standardmäßig 10 MiB) durch diesen Durchschnitt, um die maximale Anzahl von Tools zu schätzen, die für eine Spezifikation dieser Form auf einen Hostnamen passen.
Kapazität erhöhen
Es gibt zwei Mechanismen, mit denen Sie die Toolkapazität über die Standardwerte hinaus erhöhen können:
- Tools auf Hostnamen verteilen: Die Antwortobergrenze von
tools/listgilt pro Hostnamen. Wenn Sie Tools auf mehrere Hostnamen innerhalb derselben Umgebungsgruppe aufteilen, wird der Spielraum pro Hostname multipliziert (vorbehaltlich des Limits von 100 Hostnamen pro Umgebungsgruppe). Durch Sharding wird das Limit pro Proxy-Bundle nicht erhöht. Das Limit von 50 MiB pro Bundle gilt weiterhin für alle Hostnamen auf einem einzelnen MCP Discovery-Proxy. - Erhöhen Sie die Größenbeschränkung für
tools/list-Antworten. Das Standardlimit beträgt 10 MiB pro Hostnamen. Sie können ihn auf bis zu 30 MiB erhöhen. Dazu müssen Sie mindestensenvs.components.runtime.resources.limits.memory,envs.components.runtime.resources.requests.memoryundenvs.components.runtime.cwcAppend.bin_setenv_max_memin Ihreroverrides.yamlfestlegen und dannhelm upgradefür dasapigee-org-Diagramm ausführen. Das vollständige Verfahren, einschließlich der Varianten pro Umgebung und der gesamten Installation, der Anleitung zur Größenanpassung des Message Processor-Heaps und vollständigeroverrides.yaml-Beispiele finden Sie unter Unterstützung für große Nachrichtennutzlast in Apigee Hybrid konfigurieren. Das Erhöhen des Antwortlimits hat keine Auswirkungen auf das Größenlimit von 50 MiB für MCP-Proxy-Bundles. Wenn Ihre Kapazität durch dieses Limit eingeschränkt ist, hilft diese Änderung nicht.
Sicherheit
Vertrauensgrenze
Die MCP-Datenebene wird in Ihrem eigenen Kubernetes-Cluster ausgeführt. Google hat keinen Laufzeitzugriff auf die Datenebene. Die Apigee-Steuerungsebene stellt Ihnen eine MCP-Konfiguration bereit, die aus Ihrer OpenAPI-Spezifikation abgeleitet ist. Sie beobachtet keinen MCP-Anfragetraffic. Ruhende Konfigurationsdaten werden in einem von Apigee verwalteten Cloud Storage-Bucket gespeichert, der auf Ihr Apigee-Mandantenprojekt beschränkt ist. Sie werden vom MCP-Sidecar über das zugehörige Ambient-Google Cloud-Dienstkonto abgerufen.
Der Apigee-Operator stellt in Ihrem Apigee-Namespace (APIGEE_NAMESPACE) für das Dienstkonto der MCP-Datenebene ein Kubernetes-Role und ein Kubernetes-RoleBinding mit MCP-Bereich bereit. Die Rolle gewährt Lesezugriff:
get,list,watchaufservicesin der Core API-Gruppe.get,list,watchfürapigeeroutesin der API-Gruppeapigee.cloud.google.com.- In
1.17.4und höher:get,list,watchfürsecretsin der Core API-Gruppe. Die MCP-Datenebene verwendet dies, um das Clientzertifikat und die vonvirtualhosts[].mcpMtlsbenannten vertrauenswürdigen CA-Secrets zu lesen und ihre Rotation zu erkennen (siehe mTLS zwischen der MCP-Datenebene und dem Ingress-Gateway konfigurieren). Die Berechtigung ist schreibgeschützt, gilt aber für jedes Secret im Apigee-Namespace: Kubernetes RBAC kannlistundwatchnicht auf benannte Secrets beschränken. Sie ist vorhanden, unabhängig davon, ob für eine UmgebungsgruppemcpMtlskonfiguriert ist oder nicht.
Die Rolle gewährt keine Schreibverben und keinen Zugriff auf ConfigMaps oder den Pod-Status.
Ihr Auditor kann die genauen Regeln direkt im Cluster mit folgendem Befehl prüfen:
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
Die Rolle und RoleBinding apigee-mcp-server-APIGEE_ORG_CR sind die MCP-bezogenen RBAC-Ressourcen. Ihre Namen enthalten den vollständigen Namen Ihrer benutzerdefinierten ApigeeOrganization-Ressource, die vom Namen Ihrer Apigee-Organisation und einem kurzen Hash abgeleitet wird. Sie haben kein app=apigee-mcp-server-Label auf Ressourcenebene (nur die Pods haben eines). Daher liefert eine labelbasierte Suche keine Ergebnisse. Wenn der obige Befehl zur Feldauswahl nichts zurückgibt, listen Sie alle MCP-bezogenen RBAC-Ressourcen im Namespace mit folgendem Befehl auf:
kubectl get role,rolebinding -n APIGEE_NAMESPACE | grep apigee-mcp-server
TLS zwischen Message Processor und MCP-Datenebene
Message Processor-Pods wählen die MCP-Datenebene unter https://mcp.apigee.internal/ oder https://ORG_NAME.mcp.apigee.internal/ an. Diese Hostnamen werden über den eingefügten hostAliases-Eintrag in die ClusterIP des MCP-Dienstes aufgelöst. Der MCP-Datenebenencontainer stellt ein TLS-Zertifikat bereit, das vom vom Apigee-Operator bereitgestellten Aussteller (dem ClusterIssuer mit dem Namen apigee-ca-issuer) signiert wurde. Die alternativen Antragstellernamen des Zertifikats enthalten beide Hostnamen.
TLS zwischen der MCP-Datenebene und dem Ingress-Gateway
Die MCP-Datenebene leitet jeden Toolaufruf über den Host-Alias der Umgebungsgruppe an das Apigee Ingress-Gateway an Port 443 weiter. Standardmäßig ist diese Verbindung eine unidirektionale TLS-Verbindung und die MCP-Datenebene überprüft das Zertifikat des Ingress-Gateways nicht. In 1.17.4 und höher können Sie für diese Verbindung pro Umgebungsgruppe eine gegenseitige Authentifizierung anfordern. Weitere Informationen finden Sie unter mTLS zwischen der MCP-Datenebene und dem Ingress-Gateway konfigurieren.
Eingehenden Zugriff auf den MCP-Dienst einschränken
In Apigee Hybrid 1.17.0 authentifiziert die MCP-Datenebene ihre Aufrufer nicht unabhängig. Es wird davon ausgegangen, dass Anfragen, die es erreichen, bereits von einem Apigee-MCP-Proxy authentifiziert wurden, der im Message Processor ausgeführt wird. Der einzige vorgesehene Aufrufer des MCP-Dienstes ist der Message Processor. Jede andere clusterinterne Arbeitslast, die die MCP-Dienst-ClusterIP über TCP 443 erreichen kann, kann MCP-Tools ohne Authentifizierungsprüfung aufrufen.
Beschränken Sie den eingehenden Zugriff auf die MCP-Pods nur auf Message Processor-Pods. Verwenden Sie dazu die Cluster-Ingress-Richtlinien-Engine Ihrer Plattform (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy oder Ähnliches). Die Einschränkung:
- Eingehender Traffic zu Pods mit dem Label
app=apigee-mcp-serverim NamespaceAPIGEE_NAMESPACEüber TCP443ist nur von Pods mit dem Labelapp=apigee-runtimeim selben Namespace zulässig. - Lehnt alle anderen eingehenden Verbindungen über TCP
443zu Pods mit dem Labelapp=apigee-mcp-serverab. - Lehnt den gesamten eingehenden Traffic im Cluster über TCP
15021zu Pods mit dem Labelapp=apigee-mcp-serverab. Port15021stellt einen nicht authentifizierten Plain-HTTP-/healthz/ready-Endpunkt bereit, der von kubelet für die Bereitschaftsprüfung verwendet wird. kubelet erreicht ihn direkt über die Pod-IP-Adresse, sodass keine andere clusterinterne Arbeitslast die MCP-Pods über15021erreichen sollte.
Wenden Sie diese Einschränkung an, bevor Sie die MCP-Kurzanleitung abschließen und Ihren ersten MCP-Discovery-Proxy in einer Nicht-Entwicklungsumgebung bereitstellen.
Vertrag zur Aktualität der Konfiguration
Wenn der MCP-Sidecar eine Konfiguration erfolgreich abgerufen hat, lädt der MCP-Datenebenencontainer das abgerufene Bundle und stellt es bis zum nächsten erfolgreichen Abruf bereit. Wenn nachfolgende Pull-Vorgänge fehlschlagen (Apigee-Steuerungsebene nicht erreichbar, Cloud Storage nicht erreichbar, IAM-Berechtigung für das Watcher-Dienstkonto entfernt oder ein Fehler in einer anderen Phase der Pull-Pipeline), stellt der Sidecar-Proxy das letzte bekannte fehlerfreie Bundle unbegrenzt bereit. In 1.17.0 gibt es keine integrierte Obergrenze für die Veraltung: Der Pod bleibt Ready und der Traffic des MCP-Tools wird weiterhin über das veraltete Bundle abgewickelt. Das Signal, dass die Konfiguration nicht mehr aktualisiert wird, ist eine Sidecar-Logzeile auf der Ebene ERROR, die einen consecutive_failures-Zähler enthält. Informationen zu den spezifischen Meldungen, die der Sidecar pro Fehlerphase ausgibt, finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen.
Für regulierte Produktionsumgebungen sollten Sie bei wiederholten Erhöhungen dieses Zählers eine Benachrichtigung senden. Eine minimale Benachrichtigung ist: Seite, wenn ein MCP-Sidecar-Container eine Logzeile der Ebene ERROR mit consecutive_failures ausgibt, die einen Schwellenwert erreicht, den Sie basierend auf Ihrer Toleranz für veraltete Daten festgelegt haben. Steigende Werte weisen darauf hin, dass der Sidecar die Konfiguration nicht mehr aktualisiert. Der Sidecar stellt in der Zwischenzeit das letzte erfolgreiche Bundle bereit.
Wenn der Sidecar die Konfiguration nicht mehr aktualisiert, untersuchen Sie den Fehlermodus in den Sidecar-Logs. Weitere Informationen finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen. Das Neustarten der MCP-Pods löst das zugrunde liegende Abrufproblem nicht, da neu erstellte Pods denselben Abrufpfad verwenden.
Anforderungen an ausgehende Netzwerke
Der MCP-Sidecar (der Konfigurationscontainer in jedem MCP-Pod) benötigt ausgehenden Netzwerkzugriff auf die folgenden Endpunkte über TCP 443. Wählen Sie den Tab aus, der dem Datenstandort Ihrer Apigee-Organisation entspricht. Die erforderlichen Endpunkte unterscheiden sich.
Kein Datenstandort
| Endpunkt | Verwendet für |
|---|---|
apigee.googleapis.com |
Rufen Sie bei jeder Konfigurationsaktualisierung die aktuelle MCP-Konfigurationsreferenz für Ihre Organisation von der Apigee-Steuerungsebene ab. |
storage.googleapis.com |
Laden Sie die MCP-Konfiguration Ihrer Organisation aus Google Cloud Storage herunter. |
Datenstandort
Wenn Ihre Apigee-Organisation den Datenstandort verwendet, greift der MCP-Sidecar auf den regionalen Apigee-Steuerungsebenen-Endpunkt zu (denselben Endpunkt, den Ihre anderen Apigee Hybrid-Komponenten verwenden, konfiguriert über den Diagrammwert contractProvider in Ihrer overrides.yaml). Ersetzen Sie CONTROL_PLANE_LOCATION durch den Standort der Steuerungsebene Ihrer Organisation (z. B. us, eu).
| Endpunkt | Verwendet für |
|---|---|
CONTROL_PLANE_LOCATION-apigee.googleapis.com |
Rufen Sie bei jeder Konfigurationsaktualisierung die aktuelle MCP-Konfigurationsreferenz für Ihre Organisation vom regionalen Apigee-Steuerungsebenen-Endpunkt ab. |
storage.googleapis.com |
Laden Sie die MCP-Konfiguration Ihrer Organisation aus Google Cloud Storage herunter. Der Bucket befindet sich in der Region Ihrer Organisation. Cloud Storage leitet automatisch dorthin weiter. |
Außerdem muss der Sidecar in der Lage sein, Google Cloud-Zugriffstokens für die Umgebungsinformationen abzurufen, unter denen der Pod ausgeführt wird (über Workload Identity oder einen dateibasierten Dienstkontoschlüssel). Die spezifischen Tokenaustausch-Endpunkte hängen von Ihrem Authentifizierungspfad ab und sind dieselben, die andere Apigee Hybrid-Komponenten bereits in Ihrem Cluster verwenden. Wenn der vorhandene Apigee Hybrid-Traffic zu Google Cloud APIs von diesem Namespace aus erfolgreich ist, ist auch der Tokenaustausch des MCP-Sidecars erfolgreich.
Außerdem benötigt der Sidecar clusterinternen Zugriff auf den Kubernetes API-Server (über die standardmäßige clusterinterne Dienstadresse), um seinen Aktivitäts- und Bereitschaftsstatus zu veröffentlichen. Dieser Traffic verlässt Ihren Cluster nie.
Fehlerbehebung
Eine vollständige Diagnose-Checkliste finden Sie unter Fehlerbehebung bei MCP-Bereitstellungen. Diese enthält eine clusterseitige Diagnose-Checkliste für Apigee Hybrid.
Häufige Installationsfehler
| Symptom | Ursache und Lösung |
|---|---|
helm upgrade wird abgeschlossen, aber es werden keine MCP-Ressourcen angezeigt. |
Das Organisationsdiagramm wurde vor dem Operatordiagramm aktualisiert. Führen Sie zuerst helm upgrade APIGEE_OPERATOR_RELEASE_NAME apigee-operator/ und dann helm upgrade APIGEE_ORG_RELEASE_NAME apigee-org/ noch einmal aus. |
MCP-Pods bleiben im Status ContainerCreating oder 1/2 Ready hängen. |
Zwei häufige Ursachen: Das cert-manager-Certificate für MCP wurde noch nicht ausgestellt oder das Abrufen des Container-Images schlägt fehl. Führen Sie kubectl describe pod auf dem betroffenen Pod aus, um den genauen Grund zu ermitteln. |
Sidecar-Logs (apigee-mcp-server-config) melden no MCP config from CP yet; skipping tick, pod stays Ready via seed bei jeder Abfrage. |
Erwarteter stabiler Zustand, wenn noch kein MCP Discovery-Proxy für Ihre Organisation bereitgestellt wurde. Die Apigee-Steuerungsebene gibt eine leere Konfigurationsreferenz zurück und auf der MCP-Datenebene ist nur der Kubernetes-Bereitschafts-Listener an Port 15021 geladen. Der MCP-Anfrageport 8443 hat noch keinen Listener und Anfragen an https://mcp.apigee.internal/mcp erhalten eine Verbindungsablehnung. Wenn Sie in den Bereitstellungsstatus wechseln möchten, folgen Sie der MCP-Kurzanleitung, um einen MCP-Discovery-Proxy in einer Umgebung in der Umgebungsgruppe bereitzustellen, die von diesem Cluster bedient wird. |
Sidecar-Logs melden CP fetch failed mit einem eingebetteten HTTP-403 oder PermissionDenied. |
Das Google Cloud-Dienstkonto des Apigee-Watchers hat die Rolle roles/apigee.runtimeAgent (die die vom Sidecar benötigte Berechtigung apigee.runtimeconfigs.get gewährt) in Ihrem Apigee-Mandantenprojekt verloren. Diese Rolle wird bei der Apigee Hybrid-Basisinstallation automatisch zugewiesen. Wenn sie durch eine IAM-Automatisierung entfernt wurde, weisen Sie sie dem Google Cloud-Dienstkonto apigee-watcher noch einmal zu. |
Sidecar-Logs melden CP fetch failed mit context deadline exceeded, DNS-Fehler oder TLS-Fehler. |
Der Sidecar kann apigee.googleapis.com oder storage.googleapis.com nicht von innerhalb Ihres Clusters erreichen. Prüfen Sie den ausgehenden Traffic anhand der drei Endpunkte, die oben unter Anforderungen an ausgehenden Netzwerktraffic aufgeführt sind. |
Message Processor-Pods wurden nach helm upgrade nicht neu gestartet. |
Prüfen Sie, ob der Eintrag hostAliases auf jedem MP-Pod vorhanden ist: kubectl get pods -n APIGEE_NAMESPACE -l app=apigee-runtime -o
jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'.
Wenn ein Pod leer ist, erzwingen Sie ein neues Rendering, indem Sie den Pod (kubectl delete pod -n APIGEE_NAMESPACE -l app=apigee-runtime) löschen. Der ApigeeDeployment-Controller erstellt ihn dann anhand der aktuellen Spezifikation neu, die den Eintrag hostAliases enthält. Verwenden Sie nicht kubectl rollout restart deploy, da dies nicht für ApigeeDeployment gilt. |
In den MP-Pod-Logs werden TLS-Handshake-Fehler beim Wählen von https://mcp.apigee.internal/ oder https://ORG_NAME.mcp.apigee.internal/ angezeigt, nachdem der MCP-Tool-Traffic über den Schnellstart fließt. |
Der MCP-Datenebenencontainer stellt ein Zertifikat bereit, dessen Subject Alternative Names (SANs) nicht den Hostnamen enthalten, den der MP gewählt hat. Überprüfen Sie das Zertifikat: kubectl get cert -n APIGEE_NAMESPACE | grep apigee-mcp-server und dann kubectl get cert -n APIGEE_NAMESPACE CERT_NAME -o yaml. Der dnsNames des Zertifikats muss sowohl mcp.apigee.internal als auch den kleingeschriebenen ORG_NAME.mcp.apigee.internal enthalten. Wenn dies nicht der Fall ist, löschen Sie die MCP-Ressource Certificate und lassen Sie cert-manager neu ausstellen. |
Nächste Schritte
- Folgen Sie der MCP-Kurzanleitung, um Ihren ersten MCP-Discovery-Proxy bereitzustellen und ein MCP-Tool von einem MCP-Client aus aufzurufen.
- Informationen zum Verwalten des Zugriffs auf MCP-Tools mit API-Produkten
- MCP-Traffic überwachen und analysieren
- Weitere Informationen zur erweiterten Diagnose finden Sie im Leitfaden zur Fehlerbehebung für MCP.