Orchestrator user guide

• Unattended or automated access without a user login (client credentials grant)
• Third-party integrations that perform their own OAuth flow, such as Copilot Studio or ChatGPT (authorization code grant)
• Desktop or mobile apps where no client secret can be stored safely (authorization code grant with PKCE)

• Whether the app is confidential or non-confidential.
• Whether it uses application scopes or user scopes.

Confidential vs non-confidential apps​

Application scopes vs user scopes​

• Application scopes only → client_credentials is permitted
• User scopes only → authorization_code is permitted
• Both → both are permitted

Prerequisites​

• You can access Admin > External Apps in UiPath.
• You can manage folder access in Orchestrator.

Create the external application​

1. Go to UiPath, select Admin, then External Apps.

2. Select Add Application.

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

4. Select the Application scope(s) tab.

   Important:

   Add scopes under the Application scope(s) tab, not the User scope(s) tab.

5. Add the following scopes:

   • OR.Execution: required for listing tools. MCP Servers calls the Orchestrator ListReleases API to fetch process metadata when handling tools/list, and that endpoint is authorized with OR.Execution.
   • OR.Jobs: required for executing tools. All MCP Server types that run processes as tools (UiPath, Coded, and Command) call the Orchestrator StartJobs API, which is authorized with OR.Jobs.

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

Assign the external app to the folder​

1. In Orchestrator, navigate to Tenant > Manage Access, or to the specific folder's access settings.

2. Add the external app with the Automation User role.

   This role includes the MCPServers.View permission required to access MCP Servers.

Authenticate using the external app​

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

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

Result​

Understanding scope combinations​

• tools/list: MCP Servers calls odata/Releases/ListReleases to fetch process metadata. The Releases controller requires OR.Execution.
• tools/call: MCP Servers calls odata/Jobs/StartJobs to execute a process. The Jobs controller requires OR.Jobs.

• Requesting OR.Default only is the simplest setup. Orchestrator checks the roles the external app has been assigned in each folder. The Automation User role covers both Releases and Jobs access.
• Adding specific scopes such as OR.Execution or OR.Jobs (with or without OR.Default) changes how folder resolution works. Orchestrator checks both scope claims and folder role permissions, and access is granted if either check passes. This requires the X-UIPATH-FolderKey header on every API call. MCP Servers handles this automatically by detecting the token's scopes and making per-folder calls when needed.
• Without OR.Default, specific OR.* scopes bypass folder-level role resolution and grant access across all folders within the tenant. The X-UIPATH-FolderKey header is still required for API routing.

Known limitation: GetFoldersForCurrentUser​

export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server
export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server

Common mistake: machine credentials vs external app​

{"error":"invalid_scope","error_description":"..."}
{"error":"invalid_scope","error_description":"..."}

• The MCP Server exposes tools backed by Integration Service activities (connectors).
• You are integrating with a third-party client that performs its own OAuth flow (Copilot Studio, ChatGPT).
• You need per-user identity, access control based on who logged in, not which app is calling.

Prerequisites​

• You can access Admin > External Apps in UiPath.
• You can manage folder access in Orchestrator.
• You know the redirect URL of your client application.

Create the external application​

1. Go to UiPath, select Admin, then External Apps.

2. Select Add Application.

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

4. Select the User scope(s) tab.

   Important:

   Add scopes under the User scope(s) tab, not the Application scope(s) tab.

5. Add the following scopes:

   • OR.Execution: required for listing tools.
   • OR.Jobs: required for executing tools (Coded or Command servers).

6. Add a Redirect URL. This is the address that the user's browser is sent to after login. Use the callback URL provided by your client application.

   For Copilot Studio, use a dummy URL initially and update it after the connection is created.

7. Select Add, then copy the Client ID and Client secret.

Configure folder access​

1. In Orchestrator, navigate to Tenant > Manage Access, or to the specific folder's access settings.

2. Assign the user who will log in with the Automation User, Automation Developer, or Folder Administrator role.

   This role determines what the user can do in the folder and must include the MCPServers.View permission required to access MCP Servers.

Run the authorization code flow​

1. Redirect the user to the authorization endpoint:

   assignment

   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   

2. The user logs in through the browser and is redirected back to the callback URL with a code parameter.

3. Exchange the authorization code for a token from your server-side application:

   assignment

   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   

Result​

Variant: non-confidential app with PKCE​

1. When creating the external application, select Non-confidential instead of Confidential. Only the User scope(s) tab is available. Add OR.Execution, add OR.Jobs for Coded or Command servers, and add the redirect URL.

2. Assign only the user (not the app) to the folder with the appropriate role.

3. Use the following PKCE-based authorization flow:

   assignment

   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   

Token characteristics (user scopes)​

• JWT with sub set to the user's GUID and sub_type set to user.
• Audience: UiPath.Orchestrator.
• MCP Servers resolves the token as user identity — at the MCP Servers layer, the token follows the same code path as interactive login.
• Folder key routing does not apply (single cross-folder Orchestrator call).
• Integration Service activities work (user context is present).
• Refresh token: returned when offline_access is included in the scope parameter; not returned without it. Refresh token lifetime is 60 days.

Prerequisites​

• You can manage external applications.
• You can manage folder access in Orchestrator.
• You can configure connections in Copilot Studio.

Steps​

1. In UiPath, go to Admin > External Apps and select Add Application.

2. Set the app type to Confidential.

3. Under Resources, add Orchestrator API Access with the OR.Execution scope, and add it as both an Application scope and a User scope.

   If the MCP Server is Coded or Command type, also add OR.Jobs under both scopes.

   Adding the scope under the Application scope(s) tab is what makes step 6 work; an app with only User scopes cannot be assigned to a folder in Manage Access.

4. Enter a dummy redirect URL for now (for example, https://cloud.uipath.com).

5. Save the application, then copy the Client ID and Client secret.

6. In Orchestrator, assign the external app to the folder containing the MCP Server with the Automation User role. This works because the app was given Application scopes in step 3; an app with only User scopes cannot be folder-assigned. Also assign the tenant role Allow to be Automation User.

7. In Copilot Studio, add the MCP Server URL with OAuth 2.0 Manual authentication, using the following values:

   • Client ID: the value copied in step 5.
   • Client secret: the value copied in step 5.
   • Authorization URL: https://cloud.uipath.com/identity_/connect/authorize
   • Token URL: https://cloud.uipath.com/identity_/connect/token
   • Refresh URL: https://cloud.uipath.com/identity_/connect/token
   • Scope: OR.Default

8. Select Create in Copilot Studio. Copilot Studio generates a redirect URL, the field is greyed out before creation.

9. Copy the generated redirect URL and add it to the external app's Redirect URLs in UiPath Admin > External Apps.

10. Return to Copilot Studio and select Connect.

Result​

Prerequisites​

• You can manage external applications.
• You can create apps in ChatGPT.

Get the callback URL from ChatGPT​

1. Go to ChatGPT, select your profile, then select Apps, then Create app.
2. Enter the app name, description, and the MCP Server URL from UiPath.
3. Select Advanced settings.
4. Under Registration method, change from DCR to UserDefined OAuth Client.
5. Copy the Callback URL (https://chatgpt.com/connector/oauth/{callback_id}).
6. Keep this browser tab open.

Create the external application in UiPath​

1. Go to Admin > External Apps and select Add Application.

2. Select Confidential as the app type.

3. Add OR.Execution, OR.Jobs, and OR.Folders under both the Application scope(s) and User scope(s) tabs.

   Adding the scopes under the Application scope(s) tab is what allows the next step (folder assignment) to work; an app with only User scopes cannot be assigned to a folder in Manage Access.

4. In the Redirect URL field, paste the callback URL copied from ChatGPT.

5. Save the application, then copy the Client ID and Client secret.

Assign the external app to the folder​

1. In Orchestrator, open the folder containing the MCP Server.
2. Navigate to Manage Access > Assign.
3. Add the external app with the Automation User role.

Configure ChatGPT​

1. Return to the ChatGPT browser tab.
2. Enter the OAuth Client ID and Client secret copied from the external app.
3. Under Client registration > Token endpoint auth method, select client_secret_basic.
4. Under Scopes > Default scopes, deactivate any existing default scopes.
5. Under Scopes > Base scopes, add OR.Default.
6. Select Create.

Result​