Troubleshooting MCP Servers

Solutions for common non-authentication issues with UiPath MCP Servers, including folder errors, runtime availability, CLI or client errors, and reliability patterns for external apps and tools.

This page covers common non-authentication errors when running or calling UiPath MCP Servers. For authentication errors (401, 403, OAuth), check Troubleshooting MCP Server authentication.

400 Bad Request: "Folder key is required" (errorCode 10500)

This error appears as an HTTP 400 in the MCP client (for example the MCP Inspector), with errorCode 10500, on the first call.

The endpoint requires a folder key, but the MCP Server URL is missing the {folderKey} segment.

Verify that the URL includes the folder key:

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

The folder key is a GUID, for example dfac03c4-b7d6-44f6-86b9-6f61bdd2c681. It is not visible directly in the Orchestrator UI. To find it:

• From the browser: open developer tools, select the Network tab, navigate to the folder in Orchestrator, and look for API calls containing the folder's Key field.
• From the API: call GET /orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser. The Key property on each folder object is the GUID.
• From the MCP Servers page: the URL shown already contains the folder key.

400 Bad Request: "A folder is required for this action" (errorCode 1101)

This error appears as an HTTP 400 with errorCode 1101, coming from Orchestrator, when a tool call starts a job. It is distinct from the folder-key error above.

The external application has API access but isn't assigned to the folder.

1. Open the folder containing the MCP Server in Orchestrator.
2. Navigate to the folder's Settings tab.
3. Assign the external application with the appropriate permissions.

No runtimes available for this MCP Server (400)

On the first request of a session (the initialize call), or from Refresh tools on a Coded or Command server, the platform returns HTTP 400 with the body No runtimes available for this MCP server.

Only Coded, Command, and Self-Hosted servers can return this error. UiPath, Platform, Swagger, and Remote servers always resolve a runtime.

サーバーの種類	原因	解決方法
Coded / Command	The server starts a job on the first request. This error means the job request was accepted, but no job came back.	Check Jobs in the server's folder for a faulted or missing job.
Self-Hosted	No local runtime is connected.	Start uipath run and confirm the server shows active. For setup, check Self-hosted MCP Servers.

If an established session loses its runtime mid-session, the platform returns 404 Not Found instead of this error.

403 Forbidden

License unavailable

Orchestrator returns 403 with errorCode 10000 when no license is available for the calling identity. Check Admin > Licenses in your organization to confirm a license is available for the product edition tied to MCP Servers.

uipath run fails with "You are not authorized" (403)

This error appears in the uipath run command output in the CLI.

When you run uipath run with client credentials (external application), the SDK calls GetFoldersForCurrentUser to resolve UIPATH_FOLDER_PATH into a folder key. This Orchestrator endpoint does not support client credential authentication and rejects all OAuth tokens, accepting only interactive user login.

Option 1: Set the folder key directly

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

The SDK skips the GetFoldersForCurrentUser call entirely.

Option 2: Use interactive authentication

uipath auth

Playwright MCP "Streamable HTTP Post response completed without a reply" errors

If you're using the Playwright MCP server as a Command MCP Server, the calling client (for example ChatGPT or Claude) may intermittently surface:

"Tool of type MCP failed because: Streamable HTTP Post response completed without a reply to request with ID X"

This is a known issue in Playwright MCP's Streamable HTTP implementation, not a UiPath issue. During long-running operations, such as large DOM snapshots or page navigations with waits, the Playwright MCP server can drop the connection and terminate the session prematurely. The UiPath MCP client surfaces this correctly as an error per the MCP protocol spec, and follow-up requests fail with "Session not found."

一般的なパターン

The following patterns help prevent the errors documented above.

Verifying external app permissions

Use this sequence to confirm an external application is fully configured for MCP Server access, combining authentication, folder resolution, and a live tool call:

# 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

For the full external application setup, including scopes and folder assignment, check Authenticating with an external application.

Error handling in Python MCP Servers

When building Coded MCP Servers, handle errors so they produce useful messages for the calling LLM. FastMCP catches raised exceptions and returns them as MCP error responses:

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

For a full getting-started guide, check the uipath-mcp quick start.

Retry logic for MCP client code

When calling MCP servers from a coded agent, use retry logic for transient failures:

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