Fehlerbehebung bei MCP-Bereitstellungen in Apigee

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.

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.

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-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-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:
    {"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"}
    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.
  • error-Zeile mit einem consecutive_failures-Zähler:
    {"level":"error","ts":1787613247.74,"caller":"mcpsidecar/sidecar.go:...","msg":"mcpsidecar: ...","org":"YOUR_ORG","mcp_server_id":"default","consecutive_failures":185,"error":"<wrapped error text>"}
    Sidecar-Logs sind strukturierte JSON-Daten. Wenn Sie "level":"error" mit einem steigenden consecutive_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-watcher ist nicht in der Liste watcher_identities der Ressource controlPlaneAccess Ihrer 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.com oder storage.googleapis.com wird blockiert. Beide Endpunkte müssen von den MCP-Pods aus erreichbar sein (siehe Anforderungen an ausgehende Netzwerke im Aktivierungsverfahren).
    • Das Dienstkonto apigee-watcher kann 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.

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.

  1. Prüfe, ob die Operatorin bzw. der Operator das Feld akzeptiert hat. Die Routing-Ressource der Umgebungsgruppe muss den Block mcpMtls enthalten:
    kubectl -n APIGEE_NAMESPACE get apigeeroutes -l envGroupId=ENV_GROUP_NAME \
      -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.mcpMtls}{"\n"}{end}'
    Eine leere zweite Spalte mehrere Minuten nach dem Upgrade von apigee-virtualhost bedeutet in der Regel, dass die benutzerdefinierten Apigee-Ressourcendefinitionen im Cluster älter als 1.17.4 sind und mcpMtls nicht deklarieren, sodass der API-Server das Feld verworfen hat. (Seltener wurde das apigee-org-Diagramm, das das Watcher-Image bereitstellt, nicht auf 1.17.4 aktualisiert.) Dies geschieht, wenn ein Upgrade helm upgrade fü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 im MUTUAL-Modus lehnt es ab. Dieselben veralteten CRDs verhindern auch, dass die AIS_MCP_MTLS_*-Probleme im nächsten Schritt gemeldet werden. Prüfen und beheben mit:
    kubectl get crd apigeeroutes.apigee.cloud.google.com -o yaml | grep -c mcpMtls   # 0 means the CRDs are stale
    kubectl apply -k apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false
    Führen Sie kubectl apply im Verzeichnis der Helm-Diagramme aus und führen Sie dann das apigee-virtualhost-Upgrade für die Umgebungsgruppe noch einmal aus.
  2. Prüfen Sie, ob vom Cluster Zertifikatsprobleme gemeldet wurden. Der Watcher scannt die konfigurierten Secrets und erstellt für jedes Problem ein ApigeeIssue:
    kubectl -n APIGEE_NAMESPACE get apigeeissues -l 'ais-reason in (AIS_MCP_MTLS_CLIENT_CERT_INVALID,AIS_MCP_MTLS_CLIENT_CERT_EXPIRY,AIS_MCP_MTLS_CA_CERT_INVALID,AIS_MCP_MTLS_CA_CERT_EXPIRY)'
    kubectl -n APIGEE_NAMESPACE describe apigeeissue ISSUE_NAME
    Das Feld Spec.Details gibt das Secret und die ApigeeRouteConfig (mit dem Namen ORG_NAME-ENV_GROUP_NAME) an, zu denen das Problem gehört, sowie den spezifischen Fehler.
    Begründung Schweregrad Bedeutung Korrigieren
    AIS_MCP_MTLS_CLIENT_CERT_INVALID ERROR Das Secret für das Clientzertifikat ist nicht vorhanden (secret not found), ein cert- oder key-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ässt clientAuth aus. 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 mit clientAuth neu aus.
    AIS_MCP_MTLS_CLIENT_CERT_EXPIRY WARNING innerhalb von 14 Tagen nach Ablauf; ERROR danach Das 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_INVALID ERROR Das Secret -cacert ist nicht vorhanden (secret not found; mit sslSecret erstellen Sie es selbst), der Eintrag cacert fehlt, 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 cacert ein.
    AIS_MCP_MTLS_CA_CERT_EXPIRY WARNING innerhalb von 14 Tagen nach Ablauf; ERROR danach Ein CA-Zertifikat im Secret -cacert lä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.
    Probleme werden beim nächsten Scan automatisch zurückgezogen, nachdem das Secret korrigiert wurde.
  3. mTLS-Nachrichten des Sidecars lesen Der Container apigee-mcp-server-config protokolliert eine error-Zeile, wenn die Zertifikate einer Umgebungsgruppe nicht angewendet werden können. Jede Zeile enthält in der Regel Felder wie env_group, secret (und ein Feld für das Vertrauensgeheimnis, wenn die Kettenvalidierung aktiviert ist), einen reason-Code und den verpackten Fehlertext. Filtern Sie nach dem Codewert reason, der die stabile Kennung ist. Verlassen Sie sich nicht auf die anderen Feldnamen:
    kubectl -n APIGEE_NAMESPACE logs -l app=apigee-mcp-server -c apigee-mcp-server-config \
      | grep MCP_MTLS_
    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.

    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.

    reason Bedeutung Aktion
    MCP_MTLS_SECRET_NOT_FOUND Ein referenziertes Secret ist im Apigee-Namespace nicht vorhanden. Der Text error gibt 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 -cacert für die vertrauenswürdige Zertifizierungsstelle). Der Sidecar erkennt das neue Secret automatisch.
    MCP_MTLS_MATERIAL_UNUSABLE Das 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 clientAuth oder ein Trust-Secret ohne CA-Zertifikat. Derselbe Fehler wird als ApigeeIssue gemeldet (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_FAILED Der Sidecar konnte Secrets nicht über die Kubernetes API lesen oder beobachten (API-Server nicht verfügbar oder die MCP-Rolle hat die Berechtigung secrets verloren). Eine MCP_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 und MCP_MTLS_SECRET_READER_RECOVERED wird protokolliert, wenn der Zugriff wiederhergestellt ist. Prüfen Sie, ob die MCP-Rolle weiterhin get, list, watch für secrets gewä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 mit kubectl -n APIGEE_NAMESPACE get role | grep apigee-mcp-server.
    MCP_MTLS_PUBLISH_FAILED Die 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_GROUP Für die Umgebungsgruppe ist mcpMtls konfiguriert, aber der Wert des Labels envGroupId ist kein gültiges Pfadelement. Daher stellt die MCP-Datenebene die Gruppe über One-Way-TLS bereit und ein Ingress-Gateway im Modus MUTUAL lehnt 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. Keine ApigeeIssue meldet dies. Prüfen Sie, ob die Routingressource ein gültiges Label hat: kubectl -n APIGEE_NAMESPACE get apigeeroutes --show-labels. Führen Sie das apigee-virtualhost-Upgrade für die Umgebungsgruppe noch einmal aus, damit die Ressource aus dem Diagramm neu erstellt wird.
    MCP_MTLS_SAN_WITHOUT_CHAIN_VALIDATION Die Umgebungsgruppe, die disableChainValidation: true und disableSanValidation: false zusammen 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 disableSanValidation aus dem Block mcpMtls der Umgebungsgruppe oder setzen Sie disableChainValidation auf false zurück und geben Sie eine vertrauenswürdige Zertifizierungsstelle an (siehe disableSanValidation).
    MCP_MTLS_CONFLICTING_CONFIG Zwei 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-virtualhost für die Umgebungsgruppe noch einmal aus und prüfen Sie dann mit dem Befehl get apigeeroutes in Schritt 1, ob die Blöcke übereinstimmen. Jede Route in einer Gruppe wird vom einzelnen virtualhosts[]-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.
    Mit Ausnahme von 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_DISABLED und MCP_MTLS_SAN_VALIDATION_DISABLED zeichnen auf, dass eine Umgebungsgruppe eine Validierung deaktiviert hat, sodass die Auswahl in einer Flotte auffindbar bleibt. MCP_MTLS_MATERIAL_REMOVED ist die routinemäßige Bereinigung, nachdem eine Gruppe die Nutzung deaktiviert hat, und MCP_MTLS_COLLECTION_FAILED bedeutet, 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.

  4. 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[].caCertPath oder INGRESS_SECRET_NAME-cacert) vertraut. Prüfen Sie dies mit openssl 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.caCertPath oder MCP_CLIENT_SECRET_NAME-cacert verkettet ist oder wenn die alternativen Antragstellernamen nicht den Host-Alias der Umgebungsgruppe enthalten. Überprüfen Sie das Zertifikat mit openssl verify -CAfile MCP_TRUST_CA_FILE INGRESS_CERT_FILE und die SANs mit openssl 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 Sie mcpMtls.disableSanValidation: true für diese Umgebungsgruppe fest. Dadurch wird verhindert, dass die MCP-Datenebene den Namen im Zertifikat des Ingress-Gateways prüft.

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=1000
  • kubectl -n APIGEE_NAMESPACE describe pod -l app=apigee-mcp-server
  • kubectl -n APIGEE_NAMESPACE get pods -l app=apigee-mcp-server -o wide und kubectl -n APIGEE_NAMESPACE get svc -l app=apigee-mcp-server.
  • Aktuelle Ausgabe von overrides.yaml und helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE (wobei APIGEE_ORG_RELEASE_NAME der Name des Helm-Release für das apigee-org-Diagramm ist; Sie finden ihn mit helm list -n APIGEE_NAMESPACE | grep apigee-org). Entfernen Sie vor dem Freigeben von overrides.yaml vertrauliche Informationen, einschließlich:
    • Alle Inline-Dienstkontoschlüssel unter gcp.workloadIdentity, envs[].serviceAccountPaths oder mcpServer.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.
  • 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.