Freigeben über

Problembehandlung von MCP-Servern in Azure-Container-Apps

In diesem Artikel werden häufig auftretende Probleme behandelt, die beim Bereitstellen und Verwenden von MCP-Servern in Azure-Container-Apps auftreten können. Die Probleme sind nach Kategorie organisiert und gelten sowohl für eigenständige Container-Apps als auch für plattformverwaltete dynamische Sitzungen, sofern nicht anders angegeben.

Verbindung und Zugang

Verbindungsprobleme verhindern, dass MCP-Clients Ihren Server erreichen. Diese Probleme beziehen sich in der Regel auf Ingress-Konfiguration, DNS oder Netzwerkrichtlinien.

MCP-Client kann den Server nicht erreichen

Symptome: Verbindungstimeout- oder DNS-Auflösungsfehler beim Herstellen einer Verbindung von VS Code, GitHub Copilot oder einem anderen MCP-Client.

Ursachen und Lösungen:

Ursache Lösung
Ingress ist nicht auf external eingestellt Führen Sie az containerapp ingress show zum Überprüfen aus. Setze external: true für öffentlichen Zugriff fest.
FQDN ist falsch Führen Sie az containerapp show --query properties.configuration.ingress.fqdn aus, um den richtigen Hostnamen abzurufen.
Problem mit TLS-Zertifikaten Container-Apps stellen verwaltetes TLS bereit. Wenn Sie eine benutzerdefinierte Domäne verwenden, überprüfen Sie, ob das Zertifikat ordnungsgemäß gebunden ist.
Client befindet sich hinter einer Firewall Stellen Sie sicher, dass ausgehendes HTTPS (Port 443) zu *.azurecontainerapps.io zulässig ist.

Falscher Endpunktpfad

Symptome: 404 Not Found beim Herstellen einer Verbindung mit dem MCP-Server.

Der richtige Endpunktpfad hängt von Ihrer MCP-SDK- und Routingkonfiguration ab.

Rahmenwerk Allgemeiner Endpunktpfad Hinweise
.NET (MapMcp) /mcp Der Pfad entspricht der Route in MapMcp("/mcp")
Python (FastMCP mounted on FastAPI) /mcp Montieren Sie die SDK-App in / auf FastAPI, und das SDK fügt /mcp hinzu.
Python (FastMCP standalone) /mcp Wenn FastMCP direkt ohne Montage ausgeführt wird
Node.js (Express) /mcp Pfad entspricht der Express-Route
Java (Spring Boot SSE) /mcp SSE-Transport; Pfad im WebMvcSseServerTransportProvider-Konstruktor festgelegt
Plattformverwaltete Sitzungen Wert aus mcpServerEndpoint Vollständige URL, die von der Azure Resource Manager (ARM)-API bereitgestellt wird; Abrufen aus den Eigenschaften des Sitzungspools

Eine häufige Ursache für 404-Fehler in Python ist das Einhängen der FastMCP-App bei /mcp statt bei / auf dem FastAPI-Router. Da das SDK einen eigenen /mcp Unterpfad hinzufügt, führt die Bereitstellung an /mcp zu einem /mcp/mcp Endpunkt. Bereitstellung an / so der letzte Pfad /mcp ist.

Überprüfen Sie, ob der Endpunkt reagiert, indem Sie mit curl testen:

curl -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

CORS-Fehler in browserbasierten Clients

Symptome: Access to fetch has been blocked by CORS policy in der Browserkonsole.

Hinweis

GitHub Copilot in VS Code Desktop verwendet keine Browser-CORS. Dieses Problem betrifft nur browserbasierte MCP-Clients oder VS-Code für das Web.

Lösung: Konfigurieren von CORS in der Container-App:

az containerapp ingress cors update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --allowed-origins "https://your-trusted-domain.com" \
    --allowed-methods "GET" "POST" "OPTIONS" \
    --allowed-headers "Content-Type" "Authorization" "Mcp-Session-Id"

Warnung

Zur Fehlerbehebung können Sie --allowed-origins "*" vorübergehend einstellen. Beschränken Sie für Produktionseinsätze erlaubte Origins auf bestimmte vertrauenswürdige Domains. Anleitungen finden Sie unter Sichere MCP-Server in Container-Apps .

Protokoll und Transport

Protokollfehler treten auf, wenn die JSON-RPC Nachrichten zwischen dem MCP-Client und dem Server falsch formatiert sind oder falsch übereinstimmende Transporte verwenden.

Antwort "Methode nicht gefunden"

Symptome: JSON-RPC Reaktion mit error.code: -32601.

Ursachen:

  • Das Senden einer Anforderung vor initialize. Immer initialize zuerst senden.
  • Falsch geschriebener Methodenname. Verwenden Sie tools/list, tools/call (mit einem Schrägstrich, keine Punktnotation).
  • Verwenden von SSE-Methodennamen mit HTTP-Transport oder umgekehrt.

Fehlender oder falsch formatierter JSON-RPC Umschlag

Symptome: 400 Bad Request oder Parse error (-32700).

Lösung: Stellen Sie sicher, dass jede Anforderung die erforderlichen JSON-RPC Felder enthält:

{
    "jsonrpc": "2.0",
    "id": "unique-request-id",
    "method": "tools/call",
    "params": { ... }
}

Dies id muss eine Zeichenfolge oder Zahl sein. Das jsonrpc Feld muss genau "2.0"sein.

Transportkonflikt

Symptome: Der SSE-Client erhält 404- oder 405-Fehler. DER HTTP-Client erhält unerwarteten text/event-stream Inhaltstyp.

MCP unterstützt mehrere Transporte. Stellen Sie sicher, dass Ihr Client und Server denselben Transport verwenden.

Servertransport Der Kunde sollte Folgendes verwenden
Streaming-fähiges HTTP (StreamableHTTPServerTransport) HTTP POST zu Endpunkt
SSE (SSEServerTransport) SSE-Verbindung plus POST für Nachrichten
Plattform-verwaltete Sitzungen HTTP POST mit x-ms-apikey Header

Die meisten modernen MCP-SDKs verwenden standardmäßig HTTP mit Streaming-Funktion. Wenn Sie eine Verbindung mit einem Server herstellen, der SSE verwendet (häufig mit älteren Beispielen), wechseln Sie ihren Client in den SSE-Modus.

Hinweis

Das Java-Lernprogramm verwendet den SSE-Transport (WebMvcSseServerTransportProvider), da das MCP Java SDK noch keinen stabilen streambaren HTTP-Transport bietet. Wenn Sie eine Verbindung von VS Code herstellen, wählen Sie SSE aus und verwenden "type": "sse" in .vscode/mcp.json.

Bereitstellung und Skalierung

Bereitstellungsprobleme verhindern, dass Ihr Container ordnungsgemäß gestartet wird oder korrekt reagiert. Diese Probleme beziehen sich in der Regel auf Integritätssonden, Portkonfiguration oder Skalierungseinstellungen.

Container besteht Gesundheitschecks nicht

Symptome: Container wird wiederholt neu gestartet. Protokolle zeigen Fehler bei Gesundheitsprüfungen an.

Ursache: Die Standardmäßigen Start- und Liveness-Tests senden HTTP GET-Anforderungen an den Containerport. MCP-Endpunkte akzeptieren in der Regel nur POST-Anforderungen.

Lösung: Fügen Sie Ihrer Anwendung einen dedizierten GET /health Endpunkt hinzu, der 200 OK zurückgibt. Konfigurieren Sie dann Ihre Container-App-Probes, um diesen Endpunkt zu nutzen. Zeigen Sie keine Integritätstests am MCP-Endpunkt an.

Im folgenden Beispiel wird eine Startup-Probe hinzugefügt, die auf einen /health Pfad zeigt:

az containerapp update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --yaml probe-config.yaml

Wo probe-config.yaml die Probekonfiguration enthält:

properties:
  template:
    containers:
      - name: mcp-server
        probes:
          - type: startup
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          - type: liveness
            httpGet:
              path: /health
              port: 8080
            periodSeconds: 30

Port stimmt nicht überein

Symptome: Container startet, aber Ingress gibt 502 Bad Gatewayzurück.

Ursache: Der Container überwacht einen anderen Port als den, der von der Container-Apps-Ingress erwartet wird.

Lösung: Überprüfen der Portkonfiguration:

# Check the target port
az containerapp ingress show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query targetPort

# Update if needed
az containerapp ingress update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --target-port 8080

Stellen Sie sicher, dass die PORT Umgebungsvariable in Ihrer Anwendung dem Zielport entspricht.

Kaltstart-Latenz

Symptome: Die erste Anforderung dauert 10 bis 30 Sekunden nach einer Periode der Inaktivität.

Ursache: Container-Apps werden standardmäßig auf Null skaliert. Die erste Anforderung löst einen Kaltstart aus.

Lösungen:

  • Mindestreplikate auf 1 festlegen: az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP> --min-replicas 1
  • Erhöhen Sie das Timeout der Gesundheitsprüfung, um die Kaltstartzeit zu berücksichtigen.
  • Für MCP-Sitzungen verwaltet die Plattform die Verfügbarkeit. Die coolDownPeriodInSeconds Einstellung steuert die individuelle Sitzungsdauer, nicht die Poolverfügbarkeit.

Authentifizierung

Authentifizierungsprobleme treten in der Regel auf, wenn Sie den falschen Anmeldeinformationstyp für Ihr Hostingmodell verwenden. In der folgenden Tabelle wird der richtige Authentifizierungsansatz zusammengefasst.

Hostingmodell Richtige Kopfzeile Häufig auftretender Fehler
Eigenständige + integrierte Authentifizierung Authorization: Bearer <TOKEN> Verwenden von x-ms-apikey
Dynamische Sitzungen MCP x-ms-apikey: <KEY> Verwenden von Authorization: Bearer

401 Nicht autorisiert: eigenständige Container-App

Symptome: 401 Unauthorized Reaktion beim Herstellen einer Verbindung mit einem MCP-Server mit aktivierter integrierter Authentifizierung.

Prüfliste:

  1. Überprüfen Sie, ob das Bearertoken gültig ist: az account get-access-token --resource <APP_ID> --query accessToken
  2. Überprüfen Sie, ob das Token in der Authorization Kopfzeile gesendet wird.
  3. Überprüfen Sie, ob die Registrierung der Microsoft Entra-App audience mit der angeforderten Ressource übereinstimmt.
  4. Überprüfen Sie die --unauthenticated-client-action Einstellung. Return401 blockiert nicht authentifizierte Anforderungen; AllowAnonymous lässt sie durch.

Authentifizierungsfehler: dynamische Sitzungen MCP

Symptome: Authentifizierungsfehler beim Aufrufen des plattformverwalteten MCP-Endpunkts. Der Fehler kann als HTTP-Antwort 401 oder als JSON-RPC Fehlermeldung im Antworttext angezeigt werden. Der Fehlertyp hängt davon ab, wo in der Anforderungspipeline der Fehler auftritt.

Prüfliste:

  1. Überprüfen Sie, ob der API-Schlüssel über den x-ms-apikey Header gesendet wird (nicht Authorization).
  2. Überprüfen Sie, ob der Schlüssel von fetchMCPServerCredentials stammt und nicht von einer anderen API.
  3. Wenn Sie den Schlüssel kürzlich neu generiert haben, warten Sie bis zu fünf Minuten, bis der Cache des alten Schlüssels abläuft.
  4. Überprüfen Sie, ob sich mcpServerSettings.isMCPServerEnabled im true Session-Pool befindet.

Weitere Informationen finden Sie im Authentifizierungshandbuch.

Dynamische Sitzungen

Probleme in diesem Abschnitt gelten nur für den plattformverwalteten MCP-Server in dynamischen Sitzungen. Informationen zu Problemen mit eigenständigen Container-Apps finden Sie in den vorherigen Abschnitten.

Umgebungs-ID nicht gefunden

Symptome: tools/call Die Antwort enthält einen Fehler über die nicht vorhandene Umgebung oder Sitzung.

Ursachen:

  • Die Sitzung ist abgelaufen (Zeitlimit überschritten coolDownPeriodInSeconds).
  • Die environmentId Datei wurde nicht ordnungsgemäß aus der launchShell Antwort extrahiert.
  • Sie verwenden eine Umgebungs-ID aus einem anderen Sitzungspool.

Lösung: Rufen Sie erneut auf launchShell , um eine neue Umgebung zu erstellen.

MCP nicht im Sitzungspool aktiviert

Symptome: Nein mcpServerEndpoint in den Eigenschaften des Sitzungspools.

Lösung: Überprüfen Sie, ob MCP aktiviert ist:

az rest --method GET \
    --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.App/sessionPools/<SESSION_POOL_NAME>" \
    --uri-parameters api-version=2025-02-02-preview \
    --query "properties.mcpServerSettings"

Wenn isMCPServerEnabledfalse ist oder das Feld fehlt, stellen Sie den Sitzungspool mit dem mcpServerSettings Block erneut bereit.

Regionale Verfügbarkeit

Symptome: Die Bereitstellung schlägt mit einem Fehler "in diesem Bereich nicht verfügbar" fehl.

Ursache: Dynamische Sitzungen mit MCP sind in einer Teilmenge von Azure-Regionen während der Vorschau verfügbar.

Lösung: Überprüfen Sie die Sitzungsdokumentation für die aktuelle Liste der unterstützten Regionen.

Diagnostizieren und Debuggen

Verwenden Sie die folgenden Techniken, um Diagnoseinformationen zu sammeln, bevor Sie eine Supportanfrage einreichen.

Verwenden des Tools für die Diagnose und Problembehandlung

Das Azure-Portal bietet eine integrierte Diagnose für Ihre Container-App.

  1. Melden Sie sich beim Azure-Portal an.
  2. Wechseln Sie zu Ihrer Container-App.
  3. Wählen auf der Navigationsleiste die Option Diagnose und Problembehandlung aus.
  4. Wählen Sie eine Problembehandlungskategorie aus, die für Ihr Problem relevant ist.

Anzeigen von Containerprotokollen

Streamen Sie Protokolle aus Ihrer Container-App, um die Anwendungsausgabe und Fehler anzuzeigen:

az containerapp logs show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --follow

Testen mithilfe von Curl vor der Verwendung von MCP-Clients

Bevor Sie GitHub Copilot oder andere MCP-Clients konfigurieren, überprüfen Sie, ob der Server ordnungsgemäß reagiert, indem Sie curl verwenden:

# 1. Initialize
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

# 2. List tools
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"2","method":"tools/list"}'

Wenn beide Befehle gültige JSON-RPC Antworten zurückgeben, funktioniert der Server und das Problem ist wahrscheinlich in der Clientkonfiguration.

Überprüfen von MCP-Protokollen in VS Code

Wenn Sie GitHub Copilot als MCP-Client verwenden, überprüfen Sie die integrierten MCP-Protokolle:

  1. Öffnen Sie den Ausgabebereich (Ausgabe anzeigen>).
  2. Wählen Sie GitHub Copilot Chat - MCP aus der Dropdownliste aus.
  3. Suchen Sie nach Verbindungsfehlern, Authentifizierungsfehlern oder Toolaufrufproblemen.

Verwandte Inhalte

  • Last updated on