Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Auf dieser Seite wird beschrieben, wie Sie Probleme bei der Bereitstellung von MCP-Erkennungs-Proxys beheben können. Auf dieser Seite finden Sie Informationen zum asynchronen Bereitstellungslebenszyklus von MCP-Bereitstellungen, zur Behebung von Fehlercodes und zur Überprüfung der Laufzeitverbindung.
MCP-Bereitstellung
Die Bereitstellung eines MCP-Discovery-Proxys ist ein asynchroner, mehrstufiger Prozess, bei dem die Konfiguration vollständig in der Apigee- und Google Cloud -Infrastruktur verteilt wird, bevor die Proxy-Bereitstellung abgeschlossen ist.
Während dieser nachgelagerten Bereitstellungsschritte wird der Proxy in der Benutzeroberfläche mit dem Status Bereitstellung angezeigt. Wenn der Vorgang abgeschlossen ist, ändert sich der Status in Bereitgestellt. Dieser Status bestätigt, dass alle nachgelagerten Komponenten vollständig bereitgestellt sind und der Proxy bereit ist, Traffic zu verarbeiten.
Fehlerbehebung
In den folgenden Abschnitten werden Fehler und bekannte Probleme beschrieben, die bei der Verwendung von MCP in Apigee auftreten können.
Das Backend empfängt kein Tool-Argument am erwarteten Ort.
Problem: Ein Backend liest ein Toolargument von einem Anfrageort (dem Abfragestring, einem Header oder einem Cookie), aber die OpenAPI-Spezifikation deklariert den Parameter in an einem anderen Ort. Das Argument kommt also an einer anderen Stelle in der Backend-Anfrage an. Der Aufruf schlägt fehl oder verhält sich so, als wäre das Argument nicht vorhanden.
Symptome: Die tools/call-Anfrage ist auf der MCP-Ebene erfolgreich und der MCP-Client stellt das Argument bereit, aber das Backend antwortet so, als ob der Wert fehlen würde – z. B. mit einem 400 für einen erforderlichen Wert oder mit einem Standardwert, der anstelle des gesendeten Werts angewendet wird.
Ursache: Der Parameter wird in der OpenAPI-Spezifikation als in: header oder in: cookie deklariert. Daher sendet Apigee seinen Wert als Anfrageheader oder im Cookie-Header und nicht im Abfragestring. Ein Backend, das den Wert nur aus dem Abfragestring liest, sieht ihn nicht. Weitere Informationen finden Sie unter Platzierung von Tool-Argumenten in der Backend-Anfrage.
Lösung: Entscheiden Sie, wohin der Wert gehört, und sorgen Sie dafür, dass die Spezifikation und das Backend übereinstimmen:
- Wenn Sie den Wert im Abfragestring beibehalten möchten, deklarieren Sie den Parameter
in: query. - Wenn Sie es als Header oder Cookie senden möchten, lassen Sie die Deklaration unverändert und lesen Sie den Wert von diesem Speicherort in Ihrem Backend.
Das Backend empfängt kein Cookie mehr, das in der Anfrage des MCP-Clients enthalten war.
Problem: Ein Cookie, das mit der HTTP-Anfrage des MCP-Clients eingeht, z. B. ein Sitzungscookie von einem browserbasierten Client, erreicht bei einigen Toolaufrufen das Backend nicht.
Symptome: Das Backend verhält sich so, als wäre der Aufrufer nicht authentifiziert oder nicht in der Sitzung, und das Verhalten ist inkonsistent: Derselbe Vorgang funktioniert bei einigen Aufrufen, bei anderen jedoch nicht.
Ursache: Der Vorgang deklariert einen oder mehrere in: cookie-Parameter und die betroffenen Aufrufe haben mindestens einen davon bereitgestellt. Der Cookie-Header wird als Ganzes umgeschrieben und nicht angehängt. Daher enthält er bei diesen Aufrufen nur die deklarierten Cookie-Parameter und alle anderen Cookies werden verworfen. Bei Aufrufen, die keine Cookie-Parameter enthalten, wird der Header unverändert weitergegeben. Deshalb schlagen nur einige Aufrufe fehl. Weitere Informationen finden Sie unter Cookies in der Anfrage an Ihr Backend.
Lösung: Deklarieren Sie jedes Cookie, das das Backend benötigt, als in: cookie-Parameter für jeden Vorgang, der es benötigt. So wird der Wert immer vom Toolaufruf bereitgestellt und nicht von der Anfrage des Clients übernommen. Es gibt keine Einstellung, mit der ein nicht deklariertes Cookie beibehalten wird.
Fehlerantwort-Statuscodes für Toolaufrufe und Metadaten
Apigee-MCP-Endpunkte geben HTTP-Statuscodes zurück, die der Model Context Protocol (MCP)-Spezifikation und den zugehörigen OAuth-Standards entsprechen. Wenn Sie dieses Verhalten verstehen, können Sie Fehler in Ihrem MCP-Client oder KI-Agenten richtig behandeln.
In der folgenden Tabelle sind die Statuscodes zusammengefasst, die von Apigee-MCP-Endpunkten zurückgegeben werden:
| Szenario | HTTP-Statuscode | Antworttext |
|---|---|---|
Eine Toolausführung schlägt auf tools/call fehl (z. B. gibt die Backend-API einen 4xx- oder 5xx-Fehler zurück, z. B. einen Validierungsfehler oder ein fehlendes Pflichtfeld). |
200 OK |
Ein CallToolResult, wobei result.isError auf true gesetzt ist und die Fehlerdetails in content enthalten sind. So können der MCP-Client und der LLM-Agent den Fehler lesen und beheben (z. B. indem sie fehlende Eingaben noch einmal anfordern und es noch einmal versuchen), anstatt die Sitzung zu beenden. |
Die Metadaten der OAuth-geschützten Ressource (PRM) sind nicht konfiguriert oder können unter /.well-known/oauth-protected-resource/mcp nicht gefunden werden. |
404 Not Found |
Gibt an, dass am angeforderten Speicherort keine Metadaten für geschützte Ressourcen verfügbar sind. |
| Das Zugriffstoken fehlt, ist ungültig oder abgelaufen. | 401 Unauthorized |
Enthält eine WWW-Authenticate-Challenge, um den OAuth-Erkennungsablauf zu steuern. |
| Der Bereich des Zugriffstokens ist unzureichend. | 403 Forbidden |
Enthält eine WWW-Authenticate-Challenge, um den Autorisierungsablauf für die Hochstufung zu steuern. |
Beispiel: Antworttext für Toolausführungsfehler
Wenn ein Toolaufruf fehlschlägt, gibt Apigee MCP HTTP 200 OK zurück und meldet den Fehler im JSON-RPC-Objekt result, wobei isError auf true gesetzt ist. Der ursprüngliche Fehler, der von Ihrem Backend zurückgegeben wird, wird beibehalten: Der Antworttext des Backends wird wortgetreu (als String) in result.content[].text platziert. Wenn das Backend beispielsweise HTTP 404 mit dem Text {"error":"User 42 not found"} zurückgibt, lautet die MCP-Antwort:
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\"error\":\"User 42 not found\"}" } ], "isError": true } }
Der id entspricht dem id Ihrer tools/call-Anfrage.
Wenn das Backend keinen Antworttext zurückgibt, enthält text stattdessen eine generierte Zusammenfassung, z. B. Operation failed (HTTP 500)..
Ihr MCP-Client sollte result.isError (nicht den HTTP-Statuscode) prüfen, um einen fehlgeschlagenen Toolaufruf zu erkennen. Wenn Ihr Clientcode speziell einen HTTP-Status 4xx oder 5xx erwartet, um einen Fehler bei der Toolausführung zu signalisieren, wird der Fehler nicht erkannt, da die Antwort HTTP 200 OK ist. Aktualisieren Sie solche Clients, damit sie result.isError und das Array content lesen.
Fehler auf Protokollebene (z. B. eine fehlerhafte JSON-RPC-Anfrage) unterscheiden sich von Fehlern bei der Toolausführung: Sie werden weiterhin im JSON-RPC-Objekt error (z. B. {"jsonrpc": "2.0", "error": {"code": -32700, ...}}) und nicht in result.isError zurückgegeben.
Empfehlung: Standardkonforme MCP-Clients verarbeiten diese Statuscodes über ihre Standardlogik, sodass keine Änderungen erforderlich sind. Wenn Sie zuvor einen clientseitigen Workaround hinzugefügt haben, um nicht standardmäßige Statuscodes zu verarbeiten, z. B. das Parsen eines Antworttexts, der nicht 2xx ist, auf tools/call-Fehler oder das Behandeln einer 500-Antwort vom PRM-Endpunkt als „Metadaten nicht konfiguriert“, empfehlen wir, diesen Workaround zu entfernen. Andernfalls verwendet der Client möglicherweise weiterhin eine veraltete Verarbeitungslogik, anstatt die korrigierten Statuscodes normal zu verarbeiten.
CORS-Richtlinie für browserbasierte MCP-Aufrufe
Eine CORS-Richtlinie (Cross-Origin Resource Sharing) ist erforderlich, wenn Apigee-MCP-Aufrufe direkt von einem Browser aus erfolgen (z. B. wenn der MCP-Inspector die Einstellung „Direkt“ anstelle von „Über Proxy“ verwendet). Die MCP Discovery Proxy-Vorlage enthält standardmäßig die Apigee-CORS-Richtlinie im Anfrage-PreFlow des Proxy-Endpunkts des Proxy-Bundles, um browserbasierte Aufrufe zu ermöglichen.
Wenn Sie bei Aufrufen direkt über einen Browser CORS-bezogene Probleme feststellen, müssen Sie möglicherweise die Einstellungen der CORS-Richtlinie im PreFlow der Anfrage des Proxy-Endpunkts Ihres MCP Discovery-Proxy-Bundles anpassen.
JSON-Parsing-Fehler beim Senden einer Anfrage an den MCP-Endpunkt
Wenn Sie eine Anfrage an Ihren MCP-Endpunkt senden, erhalten Sie möglicherweise eine Fehlermeldung, die so oder ähnlich aussieht (oder mit einem anderen Fehlercode und einer anderen Meldung):
{
"error": {
"code": -32700,
"message": "JSON parse error"
},
"id": null,
"jsonrpc": "2.0"
}In diesem Fall empfehlen wir, die folgenden Informationen zu bestätigen:
- Sie haben die richtige MCP-Endpunkt-URL eingegeben.
- Ihre Anfrage ist richtig formatiert.
- Sie greifen auf eine unterstützte Methode zu.
- Sie haben Ihren MCP-Discovery-Proxy in einer unterstützten Region aktiviert und konfiguriert. Eine Liste der Regionen, für die möglicherweise Kapazitätsbeschränkungen gelten, finden Sie unter Bereitstellungsfehler.
Bereitstellungsfehler
Wenn die Bereitstellung Ihres MCP Discovery-Proxys mit dem Status Fehlgeschlagen in der Benutzeroberfläche fehlschlägt, finden Sie weitere Details in der Fehlermeldung. Häufige Fehler:
- Netzwerkkonfiguration fehlgeschlagen oder Nicht unterstütztes Schema in OAS: Diese Fehler weisen in der Regel auf ein Problem mit Ihrer OpenAPI-Spezifikation hin. Prüfen Sie, ob Ihre Spezifikation gültig ist und eine unterstützte Version verwendet.
- Kapazitätslimits für Regionen (nur Apigee): Wenn ein Fehler im Zusammenhang mit der Bereitstellung des Load Balancers auftritt oder der Bereitstellungsstatus nie zu Bereitgestellt wechselt, kann dies an vorübergehenden Kapazitätslimits der Infrastruktur in einer der folgenden Regionen liegen:
asia-east2asia-northeast3asia-southeast2australia-southeast1europe-central2europe-west12europe-west9me-central2us-central2
Versuchen Sie, den Proxy in einer Umgebung in einer anderen Region bereitzustellen, um den Fehler zu beheben. Dieser Fehlermodus gilt nicht für Apigee Hybrid, wo die Laufzeitinfrastruktur Ihr eigener Cluster ist.
- MCP im Cluster nicht aktiviert (nur Apigee Hybrid): Wenn Ihre MCP-Proxy-Bereitstellung unbegrenzt im Status Wird bereitgestellt bleibt und nie den Status Bereitgestellt erreicht, prüfen Sie, ob MCP in Ihrem Cluster aktiviert ist. Weitere Informationen finden Sie unten unter Clusterseitige Diagnose.
Clusterseitige Diagnose (nur Apigee Hybrid)
Da die Apigee Hybrid-MCP-Datenebene in Ihrem eigenen Kubernetes-Cluster ausgeführt wird, werden clusterinterne Fehlermodi mit kubectl für den Cluster diagnostiziert.
Gehen Sie die folgende Diagnose-Checkliste der Reihe nach durch.
Schritt 1: Prüfen, ob MCP im Cluster aktiviert ist
MCP wird als benutzerdefinierte ApigeeDeployment-Ressource (vom Apigee-Operator verwaltet) und nicht als Vanilla-Kubernetes-Deployment bereitgestellt. Prüfen Sie, ob der MCP ApigeeDeployment vorhanden ist:
kubectl -n APIGEE_NAMESPACE get apigeedeployment -l app=apigee-mcp-server
Erwartete Ausgabe (Ressourcennamen enthalten ein von der Organisation abgeleitetes Suffix, das hier als ORG_CR_SUFFIX dargestellt wird):
NAME STATE NESTEDSTATE AGE apigee-mcp-server-default-ORG_CR_SUFFIX running 1h
Wenn der Befehl No resources found in APIGEE_NAMESPACE namespace. zurückgibt, ist MCP nicht aktiviert. Kehren Sie zu MCP in Apigee Hybrid aktivieren zurück und prüfen Sie, ob enableMcpServer: true als Schlüssel auf oberster Ebene in Ihrer overrides.yaml festgelegt ist und ob Sie das Helm-Release apigee-operator vor dem Release apigee-org aktualisiert haben. Die richtigen helm-Befehle finden Sie in Schritt 3 und Schritt 4 des Aktivierungsverfahrens.
Schritt 2: Prüfen, ob MCP-Pods ausgeführt werden
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server
Erwartete Ausgabe (Pod-Suffixe weichen ab):
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-Namen folgen der Vorlage apigee-mcp-server-default-ORG_CR_SUFFIX-REV-POD_HASH, wobei REV die vierstellige Hybrid-Release-Überarbeitung (z. B. 1170 für Hybrid 1.17.0) und POD_HASH ein achtstelliges alphanumerisches Suffix ist, das sich für jeden Pod unterscheidet.
In jedem Pod muss 2/2 in der Spalte READY und Running in der Spalte STATUS angezeigt werden. Wenn Pods nicht Running sind, wird der Grund in kubectl -n APIGEE_NAMESPACE describe pod POD_NAME angezeigt. Häufige Ursachen sind Fehler beim Abrufen von Images (prüfen Sie den ausgehenden Traffic von Ihrem Cluster zur Image-Registry, die in Ihrer overrides.yaml konfiguriert ist) und unzureichende CPU- oder Arbeitsspeicherkapazität (erhöhen Sie mcpServer.resources.requests in overrides.yaml).
Schritt 3: Pull-Status der Sidecar-Konfiguration prüfen
Der Sidecar-Container apigee-mcp-server-config in jedem MCP-Pod ruft regelmäßig die MCP-Konfiguration von der Apigee-Steuerungsebene ab. Bei jedem Abruf wird die aktuelle Konfigurationsreferenz aus apigee.googleapis.com abgerufen und dann das referenzierte Konfigurations-Bundle aus Cloud Storage abgerufen. Die MCP-Datenebene beginnt mit der Bereitstellung von MCP-Tool-Traffic auf https://mcp.apigee.internal/mcp, sobald ein Pull-Vorgang mit einer gültigen Konfiguration erfolgreich abgeschlossen wurde.
Vor dem ersten erfolgreichen Abruf mit einer gültigen Konfiguration (entweder weil noch kein MCP-Discovery-Proxy für Ihre Organisation bereitgestellt wurde oder weil der Sidecar die Steuerungsebene nicht erreichen kann) bleiben die MCP-Pods Ready, aber Anfragen an https://mcp.apigee.internal/mcp schlagen mit Verbindung abgelehnt fehl.
Prüfen Sie die Sidecar-Logs, um festzustellen, welcher Fall vorliegt:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config --tail=100
- Wiederholte
info-Zeile, die angibt, dass keine MCP-Konfiguration von der Steuerungsebene vorhanden ist: Die Apigee-Steuerungsebene hat eine erfolgreiche Antwort zurückgegeben, aber für Ihre Organisation wurde noch kein MCP-Discovery-Proxy bereitgestellt. Dies ist der erwartete stabile Zustand während des Onboardings. Um die MCP-Datenebene in den Bereitstellungsstatus zu versetzen, stellen Sie einen MCP-Discovery-Proxy gemäß der MCP-Kurzanleitung bereit.{"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"} error-Zeile mit einemconsecutive_failures-Zähler: Sidecar-Logs sind strukturierte JSON-Daten. Wenn Sie{"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>"}"level":"error"mit einem steigendenconsecutive_failures-Zähler sehen, konnte der Sidecar-Proxy keinen Konfigurationsabruf abschließen. Der Sidecar wiederholt den Vorgang automatisch mit Backoff und setzt den Zähler beim nächsten erfolgreichen Abruf auf 0 zurück.Häufige Ursachen, die Sie prüfen sollten, wenn dieser Zähler weiter steigt:
- Das Google Cloud-Dienstkonto
apigee-watcherist nicht in der Listewatcher_identitiesder RessourcecontrolPlaneAccessIhrer Apigee-Organisation enthalten. Informationen zum Hinzufügen der Berechtigung und zum Prüfen, ob sie erteilt wurde, finden Sie im Aktivierungsverfahren unter Schritt 2: Watcher-Identität Zugriff auf die MCP-Konfiguration auf der Steuerungsebene gewähren. - Ausgehender Traffic von Ihrem Cluster zu
apigee.googleapis.comoderstorage.googleapis.comwird blockiert. Beide Endpunkte müssen von den MCP-Pods aus erreichbar sein (siehe Anforderungen an ausgehende Netzwerke im Aktivierungsverfahren). - Das Dienstkonto
apigee-watcherkann von diesem Cluster keine Google Cloud-Zugriffstokens abrufen. Wenn vorhandene Apigee Hybrid-Komponenten im selben Namespace ebenfalls Authentifizierungsfehler melden, beheben Sie zuerst das gemeinsame Authentifizierungsproblem. - Ein vorübergehender Fehler der Apigee-Steuerungsebene oder von Cloud Storage. Wenn der Zähler nach dem Ausschließen der oben genannten Ursachen über einen längeren Zeitraum weiter steigt, wenden Sie sich an den Apigee-Support.
- Das Google Cloud-Dienstkonto
Schritt 4: Prüfen, ob Message Processor-hostAliases eingefügt wurden
Wenn Sie MCP aktivieren, fügt der Apigee-Operator einen hostAliases-Eintrag in die Pod-Spezifikation des Message Processor (MP) ein. Der Eintrag enthält eine IP-Adresse (die MCP-Dienst-ClusterIP) und zwei Hostnamen: mcp.apigee.internal und den kleingeschriebenen ORG_NAME.mcp.apigee.internal. Prüfen Sie, ob die Injektion erfolgreich war:
kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-runtime \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.hostAliases}{"\n"}{end}'
Jeder aufgeführte MP-Pod muss einen hostAliases-Eintrag haben, der sowohl mcp.apigee.internal als auch die kleingeschriebene ORG_NAME.mcp.apigee.internal enthält, die auf die ClusterIP des MCP-Dienstes verweist. Alle MP-Pods, die einen leeren oder fehlenden Eintrag enthalten, wurden vor der Aktivierung von MCP erstellt. Löschen Sie den betroffenen MP-Pod, damit der ApigeeDeployment-Controller ihn aus der aktuellen Pod-Spezifikation neu erstellt (die den eingefügten hostAliases-Eintrag enthält):
kubectl -n APIGEE_NAMESPACE delete pod -l app=apigee-runtime
Schritt 5: End-to-End-Überprüfung
Wenn Sie einen End-to-End-Test durchführen möchten, bei dem eine tatsächliche MCP-initialize-Anfrage über die MCP-Datenebene gesendet wird, stellen Sie einen MCP-Discovery-Proxy bereit und folgen Sie der MCP-Kurzanleitung.
Bevor ein MCP Discovery Proxy für Ihre Organisation bereitgestellt wird, schlagen Anfragen an https://mcp.apigee.internal/mcp mit Verbindung abgelehnt fehl, unabhängig davon, ob der Message Processor die MCP-Pods erreichen kann (siehe Schritt 3).
Schritt 6: mTLS zum Ingress-Gateway prüfen (falls konfiguriert)
Dieser Schritt gilt nur, wenn Sie virtualhosts[].mcpMtls für eine Umgebungsgruppe konfiguriert haben (Apigee Hybrid 1.17.4 und höher). Das typische Symptom eines mTLS-Problems ist, dass MCP-Toolaufrufe an eine Umgebungsgruppe fehlschlagen (normalerweise 503 Service Unavailable), während Aufrufe an andere Umgebungsgruppen erfolgreich sind, da die MCP-Datenebene ihre Zertifikatskonfiguration pro Umgebungsgruppe beibehält.
- Prüfe, ob die Operatorin bzw. der Operator das Feld akzeptiert hat. Die Routing-Ressource der Umgebungsgruppe muss den Block
mcpMtlsenthalten: Eine leere zweite Spalte mehrere Minuten nach dem Upgrade vonkubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \ -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
apigee-virtualhostbedeutet in der Regel, dass die benutzerdefinierten Apigee-Ressourcendefinitionen im Cluster älter als1.17.4sind undmcpMtlsnicht deklarieren, sodass der API-Server das Feld verworfen hat. (Seltener wurde dasapigee-org-Diagramm, das das Watcher-Image bereitstellt, nicht auf1.17.4aktualisiert.) Dies geschieht, wenn ein Upgradehelm upgradefür das Operator-Diagramm ausgeführt wurde, aber der Schritt Aktualisierte Apigee-CRDs installieren übersprungen wurde. Die MCP-Datenebene verwendet dann weiterhin einseitiges TLS und das Ingress-Gateway imMUTUAL-Modus lehnt es ab. Dieselben veralteten CRDs verhindern auch, dass dieAIS_MCP_MTLS_*-Probleme im nächsten Schritt gemeldet werden. Prüfen und beheben mit: Führen Siekubectl 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
kubectl applyim Verzeichnis der Helm-Diagramme aus und führen Sie dann dasapigee-virtualhost-Upgrade für die Umgebungsgruppe noch einmal aus. - Prüfen Sie, ob vom Cluster Zertifikatsprobleme gemeldet wurden. Der Watcher scannt die konfigurierten Secrets und erstellt für jedes Problem ein
ApigeeIssue: Das Feldkubectl -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.Detailsgibt das Secret und dieApigeeRouteConfig(mit dem NamenORG_NAME-ENV_GROUP_NAME) an, zu denen das Problem gehört, sowie den spezifischen Fehler.
Probleme werden beim nächsten Scan automatisch zurückgezogen, nachdem das Secret korrigiert wurde.Begründung Schweregrad Bedeutung Korrigieren AIS_MCP_MTLS_CLIENT_CERT_INVALIDERRORDas Secret für das Clientzertifikat ist nicht vorhanden ( secret not found), eincert- oderkey-Eintrag fehlt, ein Eintrag ist leer oder nicht im PEM-Format, das Zertifikat und der Schlüssel stimmen nicht überein oder die erweiterte Schlüsselverwendung des Zertifikats lässtclientAuthaus. Die MCP-Datenebene lädt sie nicht.Erstellen oder korrigieren Sie das Secret (Option 2) oder die Dateien, gefolgt von helm upgrade(Option 1). Wenn die erweiterte Schlüsselverwendung das Problem ist, stellen Sie das Zertifikat mitclientAuthneu aus.AIS_MCP_MTLS_CLIENT_CERT_EXPIRYWARNINGinnerhalb von 14 Tagen nach Ablauf;ERRORdanachDas Clientzertifikat läuft bald ab oder ist bereits abgelaufen. Ein abgelaufenes Zertifikat wird weiterhin angezeigt. Das Ingress-Gateway lehnt den Handshake ab. Rotieren Sie das Zertifikat wie unter Zertifikate rotieren beschrieben. AIS_MCP_MTLS_CA_CERT_INVALIDERRORDas Secret -cacertist nicht vorhanden (secret not found; mitsslSecreterstellen Sie es selbst), der Eintragcacertfehlt, der Eintrag ist nicht PEM, ein Block ist kein Zertifikat oder ein Zertifikat darin ist kein CA-Zertifikat.Erstellen Sie bei Bedarf das Secret und fügen Sie das CA-Zertifikat (oder die Kette), das das Zertifikat des Ingress-Gateways signiert hat, in den Eintrag cacertein.AIS_MCP_MTLS_CA_CERT_EXPIRYWARNINGinnerhalb von 14 Tagen nach Ablauf;ERRORdanachEin CA-Zertifikat im Secret -cacertläuft bald ab oder ist abgelaufen. Nach Ablauf vertraut die MCP-Datenebene der Zertifikatskette des Ingress-Gateways nicht mehr.Ersetzen Sie das CA-Zertifikat im Secret -cacert, bevor es abläuft, zusammen mit dem eigenen Zertifikat des Ingress-Gateways, wenn dieses ebenfalls neu ausgestellt wird. - mTLS-Nachrichten des Sidecars lesen Der Container
apigee-mcp-server-configprotokolliert eineerror-Zeile, wenn die Zertifikate einer Umgebungsgruppe nicht angewendet werden können. Jede Zeile enthält in der Regel Felder wieenv_group,secret(und ein Feld für das Vertrauensgeheimnis, wenn die Kettenvalidierung aktiviert ist), einenreason-Code und den verpackten Fehlertext. Filtern Sie nach dem Codewertreason, der die stabile Kennung ist. Verlassen Sie sich nicht auf die anderen Feldnamen: 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 (und noch einmal, wenn es sich ändert), nicht bei jeder Aktualisierung.kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \ | grep MCP_MTLS_
Die folgenden Ursachencodes sind für die aktuelle Version stabil. Wenn Sie einen Code sehen, der nicht aufgeführt ist, wenden Sie sich an den Google Cloud Customer Care.
Mit Ausnahme vonreasonBedeutung Aktion MCP_MTLS_SECRET_NOT_FOUNDEin referenziertes Secret ist im Apigee-Namespace nicht vorhanden. Der Text errorgibt den Namen an und ob es sich um das Client- oder Trust-Secret handelt.Erstellen Sie das Secret mit dem genauen Namen (denken Sie an das Suffix -cacertfür die vertrauenswürdige Zertifizierungsstelle). Der Sidecar erkennt das neue Secret automatisch.MCP_MTLS_MATERIAL_UNUSABLEDas Secret ist vorhanden, aber sein Inhalt wird abgelehnt: ein fehlender oder leerer Datenschlüssel, ein Inhalt, der nicht PEM ist, ein Zertifikat und ein Schlüssel, die nicht übereinstimmen, ein Clientzertifikat ohne clientAuthoder ein Trust-Secret ohne CA-Zertifikat. Derselbe Fehler wird alsApigeeIssuegemeldet (vorheriger Schritt).Korrigieren Sie den Secret-Inhalt. Wenn Sie das Secret bearbeiten, wird ein neuer Versuch ausgelöst. MCP_MTLS_SECRET_READ_FAILED,MCP_MTLS_SECRET_WATCH_FAILED,MCP_MTLS_SECRET_ACCESS_FAILEDDer Sidecar konnte Secrets nicht über die Kubernetes API lesen oder beobachten (API-Server nicht verfügbar oder die MCP-Rolle hat die Berechtigung secretsverloren). EineMCP_MTLS_SECRET_READ_FAILED-Zeile enthält den Wiederholungskontext und der Sidecar wiederholt den Vorgang mit Backoff. Die anderen beiden Zeilen melden den Status der Secret-Überwachung des Sidecars undMCP_MTLS_SECRET_READER_RECOVEREDwird protokolliert, wenn der Zugriff wiederhergestellt ist.Prüfen Sie, ob die MCP-Rolle weiterhin get,list,watchfürsecretsgewährt (siehe Vertrauensgrenze) und ob andere Komponenten im Namespace den API-Server erreichen können. Der Rollenname endet mit einem generierten Suffix. Suchen Sie ihn daher mitkubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.MCP_MTLS_PUBLISH_FAILEDDie Zertifikate waren gültig, konnten aber nicht in das In-Memory-Volume des MCP-Pods geschrieben werden. Der Sidecar wiederholt den Vorgang mit Backoff und protokolliert MCP_MTLS_PUBLISH_RECOVERED, wenn der Schreibvorgang erfolgreich ist.Dies ist im Normalbetrieb nicht zu erwarten. Wenn das Problem wiederholt auftritt, erfassen Sie die Sidecar-Logs und wenden Sie sich an den Google Cloud Customer Care. MCP_MTLS_UNKEYABLE_ENV_GROUPFür die Umgebungsgruppe ist mcpMtlskonfiguriert, aber der Wert des LabelsenvGroupIdist kein gültiges Pfadelement. Daher stellt die MCP-Datenebene die Gruppe über One-Way-TLS bereit und ein Ingress-Gateway im ModusMUTUALlehnt die Toolaufrufe ab. Kubernetes-Labelregeln verhindern solche Werte normalerweise. Eine Gruppe in diesem Zustand stammt also von einer Routingressource, die direkt auf den Cluster angewendet wurde. KeineApigeeIssuemeldet dies.Prüfen Sie, ob die Routingressource ein gültiges Label hat: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Führen Sie dasapigee-virtualhost-Upgrade für die Umgebungsgruppe noch einmal aus, damit die Ressource aus dem Diagramm neu erstellt wird.MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATIONDie Umgebungsgruppe, die disableChainValidation: trueunddisableSanValidation: falsezusammen festlegt. Der SAN-Abgleich erfolgt innerhalb der Validierung, die durch die Kettenvalidierung eingerichtet wird. Wenn die Kettenvalidierung deaktiviert ist, gibt es nichts, womit ein Abgleich erfolgen könnte, und die Einstellung wird ignoriert. Das Diagramm lehnt diese Kopplung ab. Eine Gruppe in diesem Status stammt also von einer benutzerdefinierten Ressource, die direkt auf den Cluster angewendet wurde.Entfernen Sie disableSanValidationaus dem BlockmcpMtlsder Umgebungsgruppe oder setzen SiedisableChainValidationauffalsezurück und geben Sie eine vertrauenswürdige Zertifizierungsstelle an (siehedisableSanValidation).MCP_MTLS_CONFLICTING_CONFIGZwei Routing-Ressourcen in derselben Umgebungsgruppe enthalten unterschiedliche mcpMtls-Blöcke. Welcher Block von der MCP-Datenebene verwendet wird, hängt von der Reihenfolge ab, in der die Routen verarbeitet werden. Die Gruppe kann am Ende ein anderes Clientzertifikat als das von Ihnen konfigurierte präsentieren, und nichts zeichnet nachgelagert auf, welcher Block gewonnen hat.Führen Sie das Upgrade von apigee-virtualhostfür die Umgebungsgruppe noch einmal aus und prüfen Sie dann mit dem Befehlget apigeeroutesin Schritt 1, ob die Blöcke übereinstimmen. Jede Route in einer Gruppe wird vom einzelnenvirtualhosts[]-Eintrag dieser Gruppe abgeleitet. Eine Abweichung bedeutet also, dass die Ressourcen direkt auf den Cluster angewendet wurden oder ein früheres Upgrade nur teilweise weitergegeben wurde.MCP_MTLS_UNKEYABLE_ENV_GROUP, wodurch die Umgebungsgruppe auf One-Way-TLS herabgestuft wird, verwendet die Umgebungsgruppe weiterhin die letzten Zertifikate, die der Sidecar erfolgreich geladen hat. Wenn noch nie welche geladen wurden (erste Aktivierung), schlagen MCP-Toolaufrufe an diese Umgebungsgruppe fehl, bis das Problem behoben ist. Andere Umgebungsgruppen sind nicht betroffen. Nach der Fehlerbehebung ist kein Neustart des Pods erforderlich.Die verbleibenden
MCP_MTLS_-Codes erfordern keine weiteren Maßnahmen.MCP_MTLS_CHAIN_VALIDATION_DISABLEDundMCP_MTLS_SAN_VALIDATION_DISABLEDzeichnen auf, dass eine Umgebungsgruppe eine Validierung deaktiviert hat, sodass die Auswahl in einer Flotte auffindbar bleibt.MCP_MTLS_MATERIAL_REMOVEDist die routinemäßige Bereinigung, nachdem eine Gruppe die Nutzung deaktiviert hat, undMCP_MTLS_COLLECTION_FAILEDbedeutet, dass die Bereinigung nicht abgeschlossen wurde und die Zertifikatsdateien der Gruppe noch auf dem Pod vorhanden sind. Bei der nächsten Aktualisierung wird die Bereinigung wiederholt. - Wenn der Cluster kein Problem meldet und die Sidecar-Logs sauber sind, aber Toolaufrufe an die Umgebungsgruppe weiterhin fehlschlagen, wird der Handshake von einer Seite abgelehnt:
- Das Ingress-Gateway lehnt das Clientzertifikat ab, wenn der Aussteller nicht in der Zertifizierungsstelle enthalten ist, der das Ingress-Gateway für diese Umgebungsgruppe (
virtualhosts[].caCertPathoderINGRESS_SECRET_NAME-cacert) vertraut. Prüfen Sie dies mitopenssl verify -CAfile INGRESS_CA_FILE MCP_CLIENT_CERT_FILE. - Die MCP-Datenebene lehnt das Zertifikat des Ingress-Gateways ab, wenn es nicht mit der Zertifizierungsstelle in
mcpMtls.caCertPathoderMCP_CLIENT_SECRET_NAME-cacertverkettet ist oder wenn die alternativen Antragstellernamen nicht den Host-Alias der Umgebungsgruppe enthalten. Überprüfen Sie das Zertifikat mitopenssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILEund die SANs mitopenssl x509 -in INGRESS_CERT_FILE -noout -ext subjectAltName. Es wird empfohlen, das Zertifikat des Ingress-Gateways neu auszustellen, damit es den Host-Alias abdeckt. Nur wenn das nicht möglich ist, legen SiemcpMtls.disableSanValidation: truefür diese Umgebungsgruppe fest. Dadurch wird verhindert, dass die MCP-Datenebene den Namen im Zertifikat des Ingress-Gateways prüft.
- Das Ingress-Gateway lehnt das Clientzertifikat ab, wenn der Aussteller nicht in der Zertifizierungsstelle enthalten ist, der das Ingress-Gateway für diese Umgebungsgruppe (
Supportanfragen
Wenn Sie eine Supportanfrage im Zusammenhang mit der Apigee Hybrid-MCP-Datenebene öffnen, hängen Sie die folgende Ausgabe an, um die Diagnose zu beschleunigen:
kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server --all-containers --tail=1000kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-serverkubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wideundkubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.- Aktuelle Ausgabe von
overrides.yamlundhelm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE(wobeiAPIGEE_ORG_RELEASE_NAMEder Name des Helm-Release für dasapigee-org-Diagramm ist; Sie finden ihn mithelm list -n APIGEE_NAMESPACE | grep apigee-org). Entfernen Sie vor dem Freigeben vonoverrides.yamlvertrauliche Informationen, einschließlich:- Alle Inline-Dienstkontoschlüssel unter
gcp.workloadIdentity,envs[].serviceAccountPathsodermcpServer.serviceAccountPath. - Alle TLS-Zertifikate oder privaten Schlüssel unter
virtualhosts. - Die Passwortfelder für
cassandra.auth. - Alle Inline-Anmeldedaten, die von Ihren Überschreibungen an den Operator übergeben werden.
- Alle Inline-Dienstkontoschlüssel unter
- Der vollständige
curl-Befehl und die Antwort, mit der das Problem reproduziert wird.
API-Stil kann im API-Hub nicht in MCP geändert werden
Wenn im Apigee API-Hub bereits eine API-Ressource mit vorhandenen API-Vorgängen vorhanden ist, können Sie das Attribut API-Stil für diese Ressource nicht in MCP ändern. Wenn Sie eine API im Apigee API-Hub als MCP-API registrieren möchten, müssen Sie bei der ersten Registrierung der API den Stil MCP auswählen oder dafür sorgen, dass keine Vorgänge für die API-Ressource vorhanden sind, bevor Sie den Stil in MCP ändern.
Wenn andere Probleme auftreten, finden Sie unter Debugging verwenden detaillierte Informationen zur Verwendung des Debugging-Tools in der Google Cloud -Konsole, um Anfragen und Antworten an und von Ihrem MCP Discovery-Proxy zu analysieren.