- Getting started
- Best practices
- Tenant
- About the Tenant Context
- Searching for Resources in a Tenant
- Managing Robots
- Connecting Robots to Orchestrator
- Storing Robot Credentials in CyberArk
- Storing Unattended Robot Passwords in Azure Key Vault (read only)
- Storing Unattended Robot Credentials in HashiCorp Vault (read only)
- Storing Unattended Robot Credentials in AWS Secrets Manager (read only)
- Deleting Disconnected and Unresponsive Unattended Sessions
- Robot Authentication
- Robot Authentication With Client Credentials
- Configuring automation capabilities
- Solutions
- Audit
- Settings
- Registry
- Cloud robots
- Automation Suite Robots
- Folders Context
- Processes
- Jobs
- Apps
- Triggers
- Logs
- Monitoring
- Indexes
- Queues
- Assets
- Connections
- Business Rules
- Storage Buckets
- MCP Servers
- Orchestrator testing
- Resource Catalog Service
- Integrations
- Troubleshooting
Orchestrator user guide
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
uipath auth
Wrong URL format
Verify that all URL segments are correct:
https://cloud.uipath.com/{org}/{tenant}/agenthub_/mcp/{folderKey}/{slug}
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:
- Open the folder in Orchestrator.
- Navigate to Manage Access > Assign.
- Search for your external app.
- 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:
- Open the folder in Orchestrator.
- Navigate to Manage Access > Assign.
- Search for the user who will log in through the external app.
- 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:
-
Go to Admin > External Apps (not Orchestrator > Machines).
-
Select Add Application.
-
Enter a name and keep the Confidential app type.
-
Select the Application scope(s) tab.
-
Add
OR.Execution, and addOR.Jobsif needed for Coded or Command servers. -
Select Add, then copy the new Client ID and Client secret.
-
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"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.
- 401 Unauthorized
- Token expired
- Wrong URL format
- Token from wrong identity provider
- 403 Forbidden
- External app or user not assigned to folder
- Missing OR.Default scope
- GetFoldersForCurrentUser returns 403 with client credentials
- 400 Bad Request: invalid_scope
- Using machine credentials instead of external app credentials
- MCP client OAuth flow fails
- Callback URL not whitelisted
- .well-known discovery routing issue