Résolution des problèmes de serveurs MCP

Solutions pour les problèmes de non-authentification courants avec les serveurs MCP UiPath, y compris les erreurs de dossier, la disponibilité du runtime, les erreurs de CLI ou de client et les modèles de fiabilité des applications et outils externes.

Cette page couvre les erreurs d’authentification courantes lors de l’exécution ou de l’appel des serveurs MCP UiPath. Pour les erreurs d'authentification (401, 403, OAuth), vérifiez Résolution des problèmes d'authentification du serveur MCP.

400 Requête incorrecte: "Clé de dossier requise". (ErrorCode 10500)

Cette erreur apparaît sous la forme d'un HTTP 400 dans le client MCP (par exemple l'Inspecteur MCP), avec le code d'erreur 10500, lors du premier appel.

Le point de terminaison nécessite une clé de dossier, mais l’URL du serveur MCP ne contient pas le segment {folderKey}.

Vérifiez que l'URL inclut la clé de dossier:

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

La clé de dossier est un GUID, par exemple dfac03c4-b7d6-44f6-86b9-6f61bdd2c681. Il n'est pas visible directement dans l'interface utilisateur d'Orchestrator. Pour le trouver:

• À partir du navigateur: ouvrez les outils de développement, sélectionnez l'onglet Réseau , accédez au dossier dans Orchestrator et recherchez les appels d'API contenant le champ Key du dossier.
• Depuis l'API: appelez GET /orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser. La propriété Key de chaque objet de dossier est le GUID.
• À partir de la page Serveurs MCP : l’URL affichée contient déjà la clé de dossier.

400 Requête incorrecte: "Un dossier est requis pour cette action". (ErrorCode 1101)

Cette erreur s'affiche sous la forme d'une erreur HTTP 400 avec le code d'erreur 1101, provenant d'Orchestrator, lorsqu'un appel d'outil démarre une tâche. Il est distinct de l'erreur de clé de dossier ci-dessus.

L’application externe a accès à l’API, mais n’est pas affectée au dossier.

1. Ouvrez le dossier contenant le serveur MCP dans Orchestrator.
2. Accédez à l'onglet Paramètres du dossier.
3. Attribuez à l’application externe les autorisations appropriées.

Aucun runtime disponible pour ce serveur MCP (400)

Lors de la première demande d'une session (l'appel initialize ), ou à partir des outils Actualiser sur un serveur codé ou de commande, la plate-forme renvoie HTTP 400 avec le corps No runtimes available for this MCP server.

Seuls les serveurs codés, de commande et auto-hébergés peuvent renvoyer cette erreur. Les serveurs UiPath, Platform, Swagger et Distant résolvent toujours un runtime.

Type de serveur	Origine	Résolution
Codé/Commande	Le serveur démarre une tâche à la première requête. Cette erreur signifie que la demande de tâche a été acceptée, mais qu’aucune tâche n’a été renvoyée.	Recherchez les tâches dans le dossier du serveur pour les tâches défaillantes ou manquantes.
Auto-hébergé	Aucun runtime local n’est connecté.	Démarrez uipath run et confirmez que le serveur s'affiche actif. Pour la configuration, vérifiez Serveurs MCP auto-hébergés.

Si une session établie perd son runtime à la mi-session, la plate-forme renvoie 404 Not Found au lieu de cette erreur.

403 Forbidden

Licence non disponible

Orchestrator renvoie le code 403 avec le code d'erreur 10000 lorsqu'aucune licence n'est disponible pour l'identité d'appel. Vérifiez Admin > Licences dans votre organisation pour confirmer qu’une licence est disponible pour l’édition du produit liée aux serveurs MCP.

l’exécution d’uipath échoue avec le message « Vous n’êtes pas autorisé» (403)

Cette erreur apparaît dans la sortie de la commande uipath run dans la CLI.

Lorsque vous exécutez uipath run avec les informations d'identification du client (application externe), le SDK appelle GetFoldersForCurrentUser pour résoudre UIPATH_FOLDER_PATH en une clé de dossier. Ce point de terminaison Orchestrator ne prend pas en charge l’authentification des informations d’identification du client et rejette tous les jetons OAuth, acceptant uniquement la connexion utilisateur interactive.

Option 1: définir directement la clé de dossier

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

Le SDK ignore entièrement l’appel GetFoldersForCurrentUser.

Option 2: utiliser l'authentification interactive

uipath auth

Playground MCP « Réponse HTTP Streamable terminée sans réponse » Erreurs

Si vous utilisez le serveur Playwight MCP en tant que serveur MCP de type Commande, le client appelant (par exemple ChatGPT ou Claude) peut faire apparaître par intermittence:

"L'outil de type MCP a échoué car: la réponse HTTP Post Streamable est terminée sans réponse à la requête avec l'ID X"

Il s’agit d’un problème connu dans l’implémentation du protocole HTTP Streamable de Playwork MCP, et non un problème UiPath. Lors d'opérations de longue durée, telles que des instantanés DOM volumineux ou des navigations de pages avec attentes, le serveur MCP PlayWrite peut abandonner la connexion et mettre fin à la session prématurément. Le client UiPath MCP le présente correctement comme une erreur selon les spécifications du protocole MCP, et les demandes de suivi échouent avec « Session introuvable».

Modèles communs

Les modèles suivants permettent d'éviter les erreurs documentées ci-dessus.

Vérifier les autorisations d’application externe

Utilisez cette séquence pour confirmer qu’une application externe est entièrement configurée pour l’accès au serveur MCP, combinant authentification, résolution de dossier et appel d’outil en direct:

# 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

Pour la configuration complète de l’application externe, y compris les étendues et l’affectation de dossier, vérifiez l’authentification avec une application externe.

Gestion des erreurs dans les serveurs MCP Python

Lors de la création de serveurs MCP codés, gérez les erreurs afin qu'ils produisent des messages utiles pour le LLM d'appel. FastMCP détecte les exceptions déclenchées et les renvoie sous forme de réponses d'erreur MCP:

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}.")

Pour obtenir un guide de démarrage rapide complet, consultez le uipath-mcp démarrage rapide.

Logique de nouvelle tentative pour le code client MCP

Lorsque vous appelez des serveurs MCP à partir d'un agent codé, utilisez une logique de réessai pour les échecs temporaires:

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