Solução de problemas de servidores MCP

Soluções para problemas comuns de não autenticação com servidores MCP da UiPath, incluindo erros de pasta, disponibilidade de runtime, erros de CLI ou de cliente e padrões de confiabilidade para apps e ferramentas externos.

Esta página aborda erros comuns de não autenticação ao executar ou chamar servidores MCP do UiPath. Para erros de autenticação (401, 403, OAuth), consulte Solução de problemas de autenticação do servidor MCP.

Solicitação inválida 400: "a chave da pasta é necessária" (Código de erro 10500)

Esse erro aparece como um HTTP 400 no cliente MCP (por exemplo, o Inspetor MCP), com códigoDeErro 10500, na primeira chamada.

O ponto de extremidade requer uma chave de pasta, mas o URL do Servidor MCP não tem o segmento {folderKey}.

Verifique se o URL inclui a chave da pasta:

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

A chave da pasta é um GUID, por dfac03c4-b7d6-44f6-86b9-6f61bdd2c681 exemplo. Ela não é visível diretamente na interface gráfica do Orchestrator. Para encontrá-lo:

• No navegador: abra ferramentas de desenvolvedor, selecione a guia Rede , navegue até a pasta no Orchestrator e procure chamadas de API que contêm o campo Key da pasta.
• A partir da API: chame GET /orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser. A propriedade Key em cada objeto de pasta é o GUID.
• Na página Servidores MCP : a URL exibida já contém a chave da pasta.

Solicitação inválida 400: "Uma pasta é necessária para esta ação" (código de erro 1101)

Esse erro aparece como um HTTP 400 com código de erro 1101, vindo do Orchestrator, quando uma chamada de ferramenta inicia um trabalho. Ele é distinto do erro da chave da pasta acima.

O aplicativo externo tem acesso à API, mas não está atribuído à pasta.

1. Abra a pasta que contém o servidor MCP no Orchestrator.
2. Navegue até a guia Configurações da pasta.
3. Atribua o aplicativo externo com as permissões apropriadas.

Nenhum runtime disponível para este servidor MCP (400)

Na primeira solicitação de uma sessão (a chamada initialize ) ou de ferramentas de atualização em um servidor codificado ou de comando, a plataforma retorna HTTP 400 com o corpo No runtimes available for this MCP server.

Apenas servidores codificados, de comando e auto-hospedados podem retornar esse erro. Os servidores UiPath, Platform, Swagger e Remote sempre resolvem um runtime.

Tipo de Servidor	Causa	Resolution
Codificado / Comando	O servidor inicia um trabalho na primeira solicitação. Esse erro significa que a solicitação de trabalho foi aceita, mas nenhum trabalho retornou.	Verifique os trabalhos na pasta do servidor em busca de um trabalho com falha ou ausente.
Auto-hospedado	Nenhum runtime local está conectado.	Inicie uipath run e confirme o servidor aparece como ativo. Para configuração, consulte Servidores MCP auto-hospedados.

Se uma sessão estabelecida perder seu runtime no meio da sessão, a plataforma retornará 404 Not Found em vez desse erro.

403 Forbidden

Licença indisponível

O Orchestrator retorna 403 com código de erro 10000 quando não há licença disponível para a identidade da chamada. Verifique Admin > Licenças em sua organização para confirmar que uma licença está disponível para a edição do produto vinculada aos servidores MCP.

a execução do uipath falha com "Você não está autorizado" (403)

Esse erro aparece na saída do comando uipath run na CLI.

Quando você executa uipath run com credenciais do cliente (aplicativo externo), o SDK chama GetFoldersForCurrentUser para resolver UIPATH_FOLDER_PATH em uma chave de pasta. Esse ponto de extremidade do Orchestrator não é compatível com a autenticação de credenciais do cliente e rejeita todos os tokens do OAuth, aceitando apenas o login do usuário interativo.

Opção 1: definir a chave da pasta diretamente

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

O SDK ignora GetFoldersForCurrentUser totalmente a chamada.

Opção 2: usar autenticação interativa

uipath auth

Playwight MCP "Resposta HTTP Streamable Post concluída sem uma resposta" erros

Se você estiver usando o servidor MCP do Playwight como um servidor MCP de Comando, o cliente de chamada (por exemplo, ChatGPT ou Claude) pode exibir intermitentemente:

A ferramenta do tipo MCP falhou porque: a resposta HTTP Post de stream foi concluída sem uma resposta à solicitação com ID X”

Esse é um problema conhecido na implementação Streamable HTTP do Playwight MCP, não um problema da UiPath. Durante operações de longa duração, como grandes instantâneos do DOM ou navegações de páginas com esperas, o servidor MCP do Playwight pode interromper a conexão e encerrar a sessão prematuramente. O cliente UiPath MCP revela isso corretamente como um erro de acordo com as especificações do protocolo MCP, e as solicitações de acompanhamento falham com "Sessão não encontrada".

Padrões comuns

Os seguintes padrões ajudam a evitar os erros documentados acima.

Verificação de permissões de aplicativos externos

Use esta sequência para confirmar que um aplicativo externo está totalmente configurado para acessar o Servidor MCP, combinando autenticação, resolução de pastas e uma chamada de ferramenta ao 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 a configuração completa do aplicativo externo, incluindo escopos e atribuição de pastas, consulte Autenticação com um aplicativo externo.

Tratamento de erros em servidores MCP Python

Ao criar servidores MCP codificados, lide com erros para que eles produzam mensagens úteis para o LLM de chamada. O FastMCP captura exceções geradas e as retorna como respostas de erro do 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 obter um guia completo de introdução, consulte o uipath-mcp início rápido.

Lógica de nova tentativa para código de cliente MCP

Ao chamar servidores MCP de um agente codificado, use a lógica de nova tentativa para falhas transitórias:

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