Skip to main content

Troubleshooting MCP Server authentication

This page covers common errors when authenticating to UiPath MCP Servers.

401 Unauthorized​

Token expired​

The most common cause is an expired token. Re-authenticate:

uipath auth

Wrong URL format​

Verify that all URL segments are correct:

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

Where:

  • {org}: your UiPath organization name
  • {tenant}: your tenant name
  • {folderKey}: the folder's GUID
  • {slug}: the MCP Server's slug name

Token from wrong identity provider​

If you see audience validation errors in the logs, the token was likely issued for a different service. Verify that you authenticated against the correct UiPath Cloud instance.

403 Forbidden​

External app or user not assigned to folder​

The required fix depends on which scopes the external app has.

App has Application scopes (with or without User scopes)

Assign the app to the folder containing the MCP Server:

  1. Open the folder in Orchestrator.
  2. Navigate to Manage Access > Assign.
  3. Search for your external app.
  4. Assign the external app with the Automation User role.

App has only User scopes

The app itself cannot be assigned to the folder. Searching for it in Manage Access returns no results, because Orchestrator only lists apps with Application scopes. Instead, assign the user who logs in through the app:

  1. Open the folder in Orchestrator.
  2. Navigate to Manage Access > Assign.
  3. Search for the user who will log in through the external app.
  4. Assign the user with the Automation User, Automation Developer, or Folder Administrator role.

Missing OR.Default scope​

If you request a token with only specific OR.* scopes (for example, OR.Execution or OR.Jobs) without including OR.Default, the token bypasses folder-level role resolution and grants access across all folders within the tenant. Orchestrator still requires the X-UIPATH-FolderKey header on every API call.

Current MCP Servers versions handle this automatically. On older versions, this may result in failed Orchestrator calls. To avoid this issue, include OR.Default as the only scope in your token request and rely on folder role-based access instead.

GetFoldersForCurrentUser returns 403 with client credentials​

This is expected behavior. The GetFoldersForCurrentUser Orchestrator API does not support client credential authentication. To work around this, set the UIPATH_FOLDER_KEY environment variable to bypass the folder resolution call.

400 Bad Request: invalid_scope​

Using machine credentials instead of external app credentials​

This is the most common cause of invalid_scope errors. Machine credentials are for robot authentication, not for API access.

To fix this:

  1. Go to Admin > External Apps (not Orchestrator > Machines).

  2. Select Add Application.

  3. Enter a name and keep the Confidential app type.

  4. Select the Application scope(s) tab.

  5. Add OR.Execution, and add OR.Jobs if needed for Coded or Command servers.

  6. Select Add, then copy the new Client ID and Client secret.

  7. Re-authenticate using the new credentials:

    uipath auth --client-id "<new-client-id>" \
        --client-secret "<new-client-secret>" \
        --base-url "https://cloud.uipath.com/{org}/{tenant}" \
        --scope "OR.Default"

MCP client OAuth flow fails​

Callback URL not whitelisted​

UiPath Identity Server requires callback URLs to be pre-whitelisted for Dynamic Client Registration (DCR). If your MCP client's callback URL is not whitelisted, the DCR step fails.

VS Code with GitHub Copilot currently works without additional configuration. Support for additional clients (Claude Desktop, Cursor, ChatGPT) is being progressively added.

.well-known discovery routing issue​

Some MCP clients (such as Copilot Studio and OpenAI clients) probe /.well-known/openid-configuration at the root domain instead of following the resource_metadata URL from the WWW-Authenticate header. When this probe hits cloud.uipath.com/.well-known/openid-configuration, it returns an HTML 200 page instead of a proper 404, which breaks the client's discovery logic.

This is a known routing issue. If you encounter it, contact UiPath support for the latest status.