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 mit der Bereitstellung von MCP-Discovery-Proxys beheben können. Auf dieser Seite finden Sie Informationen zum asynchronen Bereitstellungslebenszyklus von MCP-Bereitstellungen, können Fehlercodes beheben und die Laufzeitverbindung prüfen.

MCP-Bereitstellung

Die Bereitstellung eines MCP-Discovery-Proxys ist ein asynchroner, mehrstufiger Prozess, der dafür sorgt, dass die Konfiguration vollständig in der Apigee- und Google Cloud -Infrastruktur übertragen wird, bevor die Proxy-Bereitstellung abgeschlossen ist.

Während dieser nachgelagerten Bereitstellungsschritte wird der Proxy in der Benutzeroberfläche mit dem Status Provisioning (Bereitstellung) angezeigt. Wenn der Vorgang abgeschlossen ist, ändert sich der Status in Bereitgestellt. Dieser Status bestätigt, dass alle nachgelagerten Komponenten vollständig bereitgestellt wurden 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.

Statuscodes für Fehlerantworten für Toolaufrufe und Metadaten

Apigee-MCP-Endpunkte geben HTTP-Statuscodes zurück, die der MCP-Spezifikation (Model Context Protocol) 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 von Apigee MCP-Endpunkten zurückgegebenen Statuscodes zusammengefasst:

Szenario HTTP-Statuscode Antworttext
Die Ausführung eines Tools schlägt bei 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 mit result.isError auf true und den Fehlerdetails in content. So können der MCP-Client und der LLM-Agent den Fehler lesen und sich erholen (z. B. durch erneutes Auffordern fehlender Eingaben und Wiederholen), anstatt die Sitzung zu beenden.
Die Metadaten der OAuth-geschützten Ressource (Protected Resource Metadata, 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 starten.
Der Bereich des Zugriffstokens ist unzureichend. 403 Forbidden Enthält eine WWW-Authenticate-Challenge, um den Ablauf für die Stufenautorisierung zu starten.

Beispiel: Text der Fehlerantwort bei der Ausführung eines Tools

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 wurde, wird beibehalten: Der Backend-Antworttext wird unverändert (als String) in result.content[].text eingefügt. Wenn das Backend beispielsweise HTTP 404 mit dem Text {"error":"User 42 not found"} zurückgibt, lautet die MCP-Antwort so:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"User 42 not found\"}"
      }
    ],
    "isError": true
  }
}

Die id stimmt mit der id Ihrer tools/call-Anfrage überein. Wenn das Back-End 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 Tool-Aufruf zu erkennen. Wenn in Ihrem Clientcode speziell ein HTTP-Statuscode 4xx oder 5xx erwartet wird, um einen Fehler bei der Ausführung eines Tools zu signalisieren, wird der Fehler nicht erkannt, da die Antwort HTTP 200 OK ist. Aktualisieren Sie diese Clients, damit sie result.isError und das content-Array lesen können.

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. Es sind also keine Änderungen erforderlich. Wenn Sie zuvor eine clientseitige Problemumgehung hinzugefügt haben, um nicht standardmäßige Statuscodes zu verarbeiten, z. B. das Parsen eines Nicht-2xx-Antworttexts für tools/call-Fehler oder die Behandlung einer 500-Antwort vom PRM-Endpunkt als „Metadaten nicht konfiguriert“, empfehlen wir, diese Problemumgehung zu entfernen. Andernfalls verwendet Ihr Client möglicherweise weiterhin die alte Logik anstelle der korrigierten Statuscodes.

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 im MCP-Inspector die Einstellung „Direkt“ anstelle von „Über Proxy“ verwendet wird). Die MCP Discovery Proxy-Vorlage enthält standardmäßig die Apigee CORS-Richtlinie im Anfrage-PreFlow des Proxy-Bundles, um browserbasierte Aufrufe zu ermöglichen.

Wenn beim direkten Aufrufen aus einem Browser CORS-bezogene Probleme auftreten, müssen Sie möglicherweise die Einstellungen der CORS-Richtlinie im Anfrage-PreFlow des Proxy-Bundles für die MCP-Erkennung anpassen.

JSON-Parsing-Fehler beim Senden einer Anfrage an den MCP-Endpunkt

Möglicherweise erhalten Sie beim Senden einer Anfrage an Ihren MCP-Endpunkt eine Fehlermeldung, die so aussieht (oder einen anderen Fehlercode und eine andere Meldung enthält): 

{
  "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 korrekt 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, in denen 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 Informationen in der Fehlermeldung. Häufige Fehler:

  • Networking configuration failed oder Unsupported Schema in OAS: Diese Fehler deuten 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 Sie einen Fehler im Zusammenhang mit einem fehlgeschlagenen Load-Balancer-Provisioning sehen oder der Provisioning-Status nie in Bereitgestellt geändert wird, kann das an vorübergehenden Infrastrukturkapazitätslimits in einer der folgenden Regionen liegen:
    • asia-east2
    • asia-northeast3
    • asia-southeast2
    • australia-southeast1
    • europe-central2
    • europe-west12
    • europe-west9
    • me-central2
    • us-central2

    Um den Fehler zu beheben, stellen Sie den Proxy in einer Umgebung in einer anderen Region bereit. Dieser Fehlermodus gilt nicht für Apigee Hybrid, da die Laufzeitinfrastruktur Ihr eigener Cluster ist.

  • MCP nicht im Cluster aktiviert (nur Apigee Hybrid): Wenn die Bereitstellung Ihres MCP-Proxys auf unbestimmte Zeit im Status Provisioning (Bereitstellung) verbleibt und nie den Status Deployed (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 Fehler im Cluster mit kubectl für den Cluster diagnostiziert. Gehen Sie die folgende Checkliste zur Fehlerbehebung der Reihe nach durch.

Schritt 1: Prüfen, ob MCP im Cluster aktiviert ist

MCP wird als benutzerdefinierte ApigeeDeployment-Ressource (verwaltet vom Apigee-Operator) und nicht als Standard-Kubernetes-Deployment bereitgestellt. Prüfen Sie, ob der MCP ApigeeDeployment 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 der obersten Ebene in Ihrer overrides.yaml festgelegt ist und ob Sie das apigee-operator-Helm-Release vor dem apigee-org-Release aktualisiert haben. Die richtigen helm-Befehle finden Sie in Schritt 3 und Schritt 4 der Anleitung zum Aktivieren.

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 können abweichen):

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-Revision ist (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 in der Spalte READY 2/2 und in der Spalte STATUS Running angezeigt werden. Wenn Pods nicht Running sind, wird in kubectl -n APIGEE_NAMESPACE describe pod POD_NAME der Grund dafür angezeigt. Häufige Ursachen sind Fehler beim Abrufen von Images (prüfen Sie den Egress von Ihrem Cluster zur in overrides.yaml konfigurierten Image-Registry) und unzureichende CPU- oder Arbeitsspeicherreserven (erhöhen Sie mcpServer.resources.requests in overrides.yaml).

Schritt 3: Status des Sidecar-Konfigurations-Pulls prüfen

Der apigee-mcp-server-config-Sidecar-Container in jedem MCP-Pod ruft regelmäßig die MCP-Konfiguration von der Apigee-Steuerungsebene ab. Bei jedem Pull wird der aktuelle Konfigurationsverweis 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 mit einer gültigen Konfiguration erfolgreich abgeschlossen wurde.

Vor dem ersten erfolgreichen Pull 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 connection refused 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
  • Wiederholung der Zeile info, die darauf hinweist, dass keine MCP-Konfiguration von der Steuerungsebene erfolgt: 
    {"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. Das ist der erwartete stabile Zustand während des Onboardings. Um die MCP-Datenebene in den Serving-Status 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-Protokolle sind strukturierte JSON-Dateien. Wenn Sie "level":"error" mit einem steigenden consecutive_failures-Zähler sehen, konnte der Sidecar-Container keine Konfiguration abrufen. Der Sidecar wird automatisch mit Backoff-Verfahren wiederholt und der Zähler wird beim nächsten erfolgreichen Pull auf 0 zurückgesetzt.

    Häufige Ursachen, die Sie prüfen sollten, wenn dieser Zähler immer weiter steigt:

    • Das Google Cloud-Dienstkonto apigee-watcher ist nicht in der Liste watcher_identities der Ressource controlPlaneAccess Ihrer Apigee-Organisation enthalten. Weitere Informationen finden Sie unter Schritt 2: Zugriff auf die MCP-Konfiguration auf der Steuerungsebene für die Watcher-Identität gewähren im Aktivierungsverfahren.
    • Ausgehender Traffic von Ihrem Cluster zu apigee.googleapis.com oder storage.googleapis.com ist blockiert. Beide Endpunkte müssen von den MCP-Pods aus erreichbar sein (siehe Anforderungen an ausgehende Netzwerke im Aktivierungsverfahren).
    • Das Dienstkonto apigee-watcher kann keine Google Cloud-Zugriffstokens von diesem Cluster abrufen. Wenn bei vorhandenen Apigee Hybrid-Komponenten im selben Namespace ebenfalls Authentifizierungsfehler auftreten, beheben Sie zuerst das gemeinsame Authentifizierungsproblem.
    • Ein vorübergehender Fehler in der Apigee-Steuerungsebene oder in Cloud Storage. Wenn der Zähler über einen längeren Zeitraum weiter ansteigt, nachdem Sie die oben genannten Ursachen ausgeschlossen haben, wenden Sie sich an den Apigee-Support.

Schritt 4: Prüfen, ob „hostAliases“ in Message Processor 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 ClusterIP des MCP-Dienstes) und zwei Hostnamen: mcp.apigee.internal und ORG_NAME.mcp.apigee.internal in Kleinbuchstaben. Prüfen Sie, ob das Einfügen 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 mit mcp.apigee.internal und dem kleingeschriebenen ORG_NAME.mcp.apigee.internal haben, der auf die MCP-Service-ClusterIP verweist. Alle MP-Pods mit einem leeren oder fehlenden Eintrag 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-Bestätigung

Für einen End-to-End-Test, 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 connection refused fehl, unabhängig davon, ob der Message Processor die MCP-Pods erreichen kann (siehe Schritt 3).

Supportanfragen

Wenn Sie eine Supportanfrage stellen, die die Apigee Hybrid MCP-Datenebene betrifft, 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 overrides.yaml- und helm history APIGEE_ORG_RELEASE_NAME -n APIGEE_NAMESPACE-Ausgabe (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 Teilen von overrides.yaml vertrauliche Informationen, darunter:
    • Alle Inline-Dienstkontoschlüssel unter gcp.workloadIdentity, envs[].serviceAccountPaths oder mcpServer.serviceAccountPath.
    • Alle TLS-Zertifikate oder privaten Schlüssel unter virtualhosts.
    • Die cassandra.auth-Passwortfelder.
    • Alle Inline-Anmeldedaten, die von Ihren Überschreibungen an den Operator übergeben werden.
  • Der vollständige curl-Befehl und die Antwort, die das Problem reproduzieren.

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 MCP-Stil 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 ausführliche Informationen zur Verwendung des Debugging-Tools in der Google Cloud Konsole, um Anfragen und Antworten an und von Ihrem MCP Discovery-Proxy zu analysieren.