Fehlerbehebung für MCP-Server

Lösungen für häufige Probleme ohne Authentifizierung mit UiPath MCP-Servern, einschließlich Ordnerfehlern, Runtime-Verfügbarkeit, CLI- oder Client-Fehlern und Zuverlässigkeitsmustern für externe Apps und Tools.

Diese Seite behandelt häufige Fehler ohne Authentifizierung beim Ausführen oder Aufrufen von UiPath-MCP-Servern. Informationen zu Authentifizierungsfehlern (401, 403, OAuth) finden Sie unter Fehlerbehebung bei der MCP-Server-Authentifizierung.

400 Ungültige Anforderung: „Ordnerschlüssel ist erforderlich“ (Fehlercode 10500)

Dieser Fehler wird im MCP-Client (z. B. im MCP-Instanz) als HTTP 400 mit Fehlercode 10500 beim ersten Aufruf angezeigt.

Der Endpunkt erfordert einen Ordnerschlüssel, aber bei der MCP-Server-URL fehlt das {folderKey} -Segment.

Stellen Sie sicher, dass die URL den Ordnerschlüssel enthält:

https://cloud.uipath.com/{org}/{tenant}/agenthub_/mcp/{folderKey}/{slug}

Der Ordnerschlüssel ist eine GUID, z. B. dfac03c4-b7d6-44f6-86b9-6f61bdd2c681. Sie ist nicht direkt auf der Orchestrator-Benutzeroberfläche sichtbar. So finden Sie ihn:

• Aus dem Browser: Öffnen Sie die Entwicklertools, wählen Sie die Registerkarte Netzwerk aus, navigieren Sie zum Ordner im Orchestrator und suchen Sie nach API-Aufrufen, die das Feld Key des Ordners enthalten.
• Über die API: Rufen Sie GET /orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser auf. Die Eigenschaft Key in jedem Ordnerobjekt ist die GUID.
• Auf der Seite „MCP-Server“ : Die angezeigte URL enthält bereits den Ordnerschlüssel.

400 Ungültige Anforderung: „Für diese Aktion ist ein Ordner erforderlich“ (Fehlercode 1101)

Dieser Fehler wird als HTTP 400 mit Fehlercode 1101 aus dem Orchestrator angezeigt, wenn ein Toolaufruf einen Auftrag startet. Er unterscheidet sich vom obigen Fehler beim Ordnerschlüssel.

Die externe Anwendung hat API-Zugriff, ist dem Ordner aber nicht zugewiesen.

1. Öffnen Sie den Ordner mit dem MCP-Server in Orchestrator.
2. Navigieren Sie zur Registerkarte Einstellungen des Ordners.
3. Weisen Sie die externe Anwendung mit den entsprechenden Berechtigungen zu.

Für diesen MCP-Server (400)sind keine Runtimes verfügbar

Bei der ersten Anforderung einer Sitzung (der initialize -Aufruf) oder von Refresh-Tools auf einem codierten oder Befehlsserver gibt die Plattform HTTP 400 mit dem Text No runtimes available for this MCP server.zurück.

Nur codierte, Befehls- und selbst gehostete Server können diesen Fehler zurückgeben. UiPath-, Platform-, Swagger- und Remote-Server lösen immer eine Runtime auf.

Servertyp	Ursache	Resolution
Codiert/Befehl	Der Server startet einen Auftrag auf die erste Anforderung. Dieser Fehler bedeutet, dass die Auftragsanforderung akzeptiert wurde, aber kein Auftrag zurückgegeben wurde.	Überprüfen Sie Aufträge im Serverordner auf einen fehlerhaften oder fehlenden Auftrag.
Selbst gehostet	Es ist keine lokale Runtime verbunden.	Starten Sie uipath run und bestätigen Sie, dass der Server aktiv angezeigt wird. Aktivieren Sie für die Einrichtung Selbst gehostete MCP-Server.

Wenn eine etablierte Sitzung ihre Runtime mitten in der Sitzung verliert, gibt die Plattform 404 Not Found anstelle dieses Fehlers zurück.

403 Forbidden

Lizenz nicht verfügbar

Der Orchestrator gibt 403 mit Fehlercode 10000 zurück, wenn für die aufrufende Identität keine Lizenz verfügbar ist. Überprüfen Sie „Administrator“ > „Lizenzen“ in Ihrer Organisation, um zu bestätigen, dass eine Lizenz für die an MCP-Server gebundene Produktversion verfügbar ist.

Die uipath-Ausführung schlägt mit „Sie sind nicht autorisiert“ fehl (403)

Dieser Fehler wird in der uipath run -Befehlsausgabe in der CLI angezeigt.

Wenn Sie uipath run mit Client-Anmeldeinformationen (externe Anwendung) ausführen, ruft das SDK GetFoldersForCurrentUser auf, um UIPATH_FOLDER_PATH in einen Ordnerschlüssel aufzulösen. Dieser Orchestrator-Endpunkt unterstützt keine Client-Anmeldeinformationen-Authentifizierung und weist alle OAuth-Token zurück und akzeptiert nur die interaktive Benutzeranmeldung.

Option 1: Legen Sie den Ordnerschlüssel direkt fest

export UIPATH_FOLDER_KEY=<your-folder-key>
uipath run my-mcp

Das SDK überspringt den GetFoldersForCurrentUser -Aufruf vollständig.

Option 2: Verwenden Sie die interaktive Authentifizierung

uipath auth

Playwright MCP „Streamable HTTP Post Antwort ohne Antwort abgeschlossen“ Fehler

Wenn Sie den Playwright MCP-Server als Befehls-MCP-Server verwenden, kann der aufrufende Client (z. B. ChatGPT oder Claude) zeitweise angezeigt werden:

„Tool vom Typ MCP ist fehlgeschlagen, weil: Streamable HTTP Post-Antwort ohne Antwort auf Anforderung mit ID X abgeschlossen wurde“

Dies ist ein bekanntes Problem in der Streamable HTTP-Implementierung von Playwright MCP, kein UiPath-Problem. Bei Vorgängen mit langer Ausführungszeit, z. B. bei großen DOM-Snapshots oder Seitennavigationen mit Wartezeiten, kann der Playwright MCP-Server die Verbindung unterbrechen und die Sitzung vorzeitig beenden. Der UiPath-MCP-Client zeigt dies korrekt als Fehler gemäß der MCP-Protokollspezifikation an, und Folgeanforderungen schlagen mit „Sitzung nicht gefunden.“ fehl.

Häufige Muster

Die folgenden Muster helfen, die oben dokumentierten Fehler zu vermeiden.

Überprüfen externer App-Berechtigungen

Verwenden Sie diese Sequence, um zu bestätigen, dass eine externe Anwendung vollständig für den MCP-Serverzugriff konfiguriert ist, indem Sie Authentifizierung, Ordnerauflösung und einen Live-Tool-Aufruf kombinieren:

# 1. Authenticate
uipath auth \
  --client-id "<client-id>" \
  --client-secret "<client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default OR.Execution OR.Jobs"

# 2. Set folder key to skip folder lookup issues
echo "UIPATH_FOLDER_KEY=<your-folder-key>" >> .env

# 3. Test with MCP Inspector or cURL
npx @modelcontextprotocol/inspector@0.22.0

Das vollständige Setup der externen Anwendung, einschließlich Scopes und Ordnerzuweisung, finden Sie unter Authentifizierung mit einer externen Anwendung.

Fehlerbehandlung in Python-MCP-Servern

Behandeln Sie beim Erstellen codierter MCP-Server Fehler, damit sie nützliche Nachrichten für das aufrufende LLM generieren. FastMCP erkennt ausgelöste Ausnahmen und gibt sie als MCP-Fehlerantworten zurück:

from mcp.server.fastmcp import FastMCP
import httpx
import os

mcp = FastMCP("My Server")

@mcp.tool()
async def get_customer(customer_id: str) -> dict:
    """Retrieve customer by ID.

    Args:
        customer_id: Customer identifier (e.g., "CUST-12345")
    """
    if not customer_id or not customer_id.startswith("CUST-"):
        raise ValueError(f"Invalid customer_id format: '{customer_id}'. Expected 'CUST-XXXXX'.")
    try:
        async with httpx.AsyncClient(timeout=30) as client:
            response = await client.get(
                f"https://api.internal.com/customers/{customer_id}",
                headers={"Authorization": f"Bearer {os.getenv('CRM_API_KEY')}"},
            )
            if response.status_code == 404:
                raise RuntimeError(f"Customer {customer_id} not found.")
            response.raise_for_status()
            return response.json()
    except httpx.TimeoutException:
        raise RuntimeError("CRM API timed out. Try again.")
    except httpx.HTTPStatusError as e:
        raise RuntimeError(f"CRM API returned {e.response.status_code}.")

Eine vollständige Anleitung für die ersten Schritte finden Sie im uipath-mcp -Schnellstart.

Wiederholungslogik für MCP-Clientcode

Wenn Sie MCP-Server von einem codierten Agent aus aufrufen, verwenden Sie die Wiederholungslogik für vorübergehende Fehler:

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def call_with_retry(url: str, token: str, tool: str, args: dict, retries: int = 3):
    """Call an MCP tool with exponential backoff."""
    for attempt in range(retries):
        try:
            async with streamablehttp_client(
                url=url,
                headers={"Authorization": f"Bearer {token}"},
                timeout=60,
            ) as (read, write, _):
                async with ClientSession(read, write) as session:
                    await session.initialize()
                    result = await session.call_tool(tool, args)
                    if result.isError:
                        raise RuntimeError(result.content[0].text if result.content else "Unknown error")
                    return result
        except Exception as e:
            if attempt < retries - 1:
                wait = 2 ** attempt
                await asyncio.sleep(wait)
            else:
                raise