Solución de problemas de servidores MCP

Soluciones para problemas comunes distintos de la autenticación con servidores MCP de UiPath, incluidos errores de carpeta, disponibilidad de runtime, errores de CLI o cliente y patrones de fiabilidad para aplicaciones y herramientas externas.

Esta página cubre los errores comunes no relacionados con la autenticación al ejecutar o llamar a servidores MCP de UiPath. Para errores de autenticación (401, 403, OAuth), consulta Resolución de problemas de autenticación del servidor MCP.

400 Solicitud incorrecta: "Se requiere la clave de la carpeta" (código de error 10500)

Este error aparece como un HTTP 400 en el cliente MCP (por ejemplo, el MCP Inspector), con errorCode 10500, en la primera llamada.

El punto final requiere una clave de carpeta, pero a la URL del servidor MCP le falta el segmento {folderKey}.

Verifica que la URL incluya la clave de la carpeta:

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

La clave de la carpeta es un GUID, por ejemplo dfac03c4-b7d6-44f6-86b9-6f61bdd2c681. No es visible directamente en la IU de Orchestrator. Para encontrarlo:

• Desde el navegador: abre las herramientas de desarrollador, selecciona la pestaña Red , navega a la carpeta en Orchestrator y busca las llamadas a la API que contengan el campo Key de la carpeta.
• Desde la API: llama a GET /orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser. La propiedad Key en cada objeto de carpeta es el GUID.
• Desde la página Servidores MCP : la URL mostrada ya contiene la clave de la carpeta.

400 Solicitud incorrecta: "Se requiere una carpeta para esta acción" (código de error 1101)

Este error aparece como un HTTP 400 con código de error 1101, procedente de Orchestrator, cuando una llamada de herramienta inicia un trabajo. Es distinto del error de clave de carpeta anterior.

La aplicación externa tiene acceso a la API, pero no está asignada a la carpeta.

1. Abre la carpeta que contiene el servidor MCP en Orchestrator.
2. Navega a la pestaña Configuración de la carpeta.
3. Asigna la aplicación externa con los permisos adecuados.

No hay tiempos de ejecución disponibles para este servidor MCP (400)

En la primera solicitud de una sesión (la llamada initialize ), o desde las herramientas de actualización en un servidor codificado o de comando, la plataforma devuelve HTTP 400 con el cuerpo No runtimes available for this MCP server.

Solo los servidores codificados, de comando y autoalojados pueden devolver este error. Los servidores UiPath, Platform, Swagger y Remote siempre resuelven un runtime.

Tipo de servidor	Causa	Resolución
Codificado/Comando	El servidor inicia un trabajo en la primera solicitud. Este error significa que se ha aceptado la solicitud de trabajo, pero no se ha devuelto ningún trabajo.	Comprueba Trabajos en la carpeta del servidor para ver si hay un trabajo defectuoso o faltante.
Autoalojado	No hay ningún runtime local conectado.	Inicie uipath run y confirme que el servidor muestra active. Para la configuración, consulta Servidores MCP autoalojados.

Si una sesión establecida pierde su runtime a mitad de sesión, la plataforma devuelve 404 Not Found en lugar de este error.

403 Forbidden

Licencia no disponible

Orchestrator devuelve 403 con errorCode 10000 cuando no hay ninguna licencia disponible para la identidad de la llamada. Consulta Admin > Licencias en tu organización para confirmar que hay una licencia disponible para la edición del producto vinculada a los servidores MCP.

la ejecución de uipath falla con "No está autorizado" (403)

Este error aparece en la salida del comando uipath run en la CLI.

Cuando ejecutas uipath run con credenciales de cliente (aplicación externa), el SDK llama a GetFoldersForCurrentUser para resolver UIPATH_FOLDER_PATH en una clave de carpeta. Este punto final de Orchestrator no admite la autenticación de credenciales de cliente y rechaza todos los tokens OAuth, aceptando solo el inicio de sesión de usuario interactivo.

Opción 1: establecer la clave de la carpeta directamente

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

El SDK omite la llamada GetFoldersForCurrentUser por completo.

Opción 2: utilizar la autenticación interactiva

uipath auth

Playwright MCP "Respuesta de publicación HTTP transmisible completada sin respuesta" Errores

Si utilizas el servidor MCP de Playwright como servidor MCP de comando, el cliente que llama (por ejemplo, ChatGPT o Claude) puede aparecer de forma intermitente:

"La herramienta de tipo MCP falló porque: la respuesta HTTP Post Streamable se completó sin una respuesta a la solicitud con ID X"

Este es un problema conocido en la implementación de HTTP Streamable de Playwright MCP, no un problema de UiPath. Durante las operaciones de larga duración, como las instantáneas DOM grandes o las navegaciones de página con esperas, el servidor MCP de Playwright puede desconectar la conexión y finalizar la sesión prematuramente. El cliente UiPath MCP muestra esto correctamente como un error según la especificación del protocolo MCP, y las solicitudes de seguimiento fallan con "Sesión no encontrada".

Patrones comunes

Los siguientes patrones ayudan a evitar los errores documentados anteriormente.

Verificar los permisos de la aplicación externa

Usa esta secuencia para confirmar que una aplicación externa está completamente configurada para el acceso al servidor MCP, combinando autenticación, resolución de carpetas y una llamada de herramienta en vivo:

# 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

Para la configuración completa de la aplicación externa, incluidos los ámbitos y la asignación de carpetas, consulta Autenticación con una aplicación externa.

Gestión de errores en servidores MCP de Python

Al crear servidores MCP codificados, gestiona los errores para que produzcan mensajes útiles para el LLM que llama. FastMCP detecta las excepciones planteadas y las devuelve como respuestas de error de 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}.")

Para obtener una guía de inicio completa, consulta el uipath-mcp inicio rápido.

Lógica de reintento para el código de cliente MCP

Al llamar a servidores MCP desde un agente codificado, utiliza la lógica de reintento para fallos transitorios:

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