# 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](./troubleshooting-mcp-server-authentication.md).

## 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.

| Server type | Cause | Resolution |
| --- | --- | --- |
| 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](./mcp-server-types.md#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**

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

The SDK skips the `GetFoldersForCurrentUser` call entirely.

**Option 2: Use interactive authentication**

```shell
uipath auth
```

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

If you're using the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) 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."

## Common patterns

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:

```shell
# 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](./authenticating-with-an-external-application.md).

### 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:

```python
from mcp.server.fastmcp import FastMCP

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](https://uipath.github.io/uipath-python/mcp/quick_start/).

### Retry logic for MCP client code

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

```python

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
```