> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UiPath integration

> Connect Voiceflow to UiPath to start approved robot jobs, check their results and use hosted MCP tools.

## Overview

Voiceflow integrates with UiPath so your AI agent can start an approved robot job, check its progress and use approved MCP tools in a customer conversation. UiPath Orchestrator owns the processes, robots, runtimes and job history. Voiceflow sends requests and uses their current results.

### Examples of when to use UiPath

- **[Generate an invoice copy](#robot-jobs)** — start an unattended process and retain its job reference.
- **[Check an existing request](#robot-jobs)** — retrieve that job's state and verified business output.
- **[Look up an order through MCP](#mcp-tools)** — connect an approved UiPath-hosted tool.
- **[Investigate a failed run](#maintaining-the-connection)** — reconcile the original job before retrying.

#### Studio

Use an editable test project in [Agent studio](https://creator.voiceflow.com). Your UiPath administrator and application developer prepare the process, credentials, trusted inputs and expected results. Obtain their verified test customer and invoice before setting up tools.

#### Developer

Use a [Voiceflow personal or service key](/docs/api-reference/authentication) with project access and a selected test [Environment](/docs/documentation/deploy/environments/overview). Set `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT`; CLI examples use the [current Voiceflow CLI](/docs/cli/install). You still need the UiPath GUI setup below. Standalone execution, agent attachment and publishing are separate operations.

<a id="connecting-uipath"></a>

## Connecting UiPath

Prepare an approved process, folder and execution identity.

These instructions use **UiPath Automation Cloud Orchestrator**. Use the actual organization and tenant URL from your administrator. Keep the process release key and folder fixed in each tool; the model must not select them. UiPath must have an existing deployed process and the unattended runtime, machine and account configuration required to run it.

### Prepare the process and credentials

#### Studio

Ask the UiPath owner to prepare the recipe below and provide:

- The Orchestrator base URL, numeric folder ID and approved process **ReleaseKey**.
- A bearer credential permitted to start and read jobs in that folder, with its expiry and rotation owner.
- The exact process input/output contract and a verified test customer/invoice.
- A successful job, its returned business output and a rejected unauthorized invoice case.

The invoice fields on this page describe an example process your team implements. They are not universal UiPath actions or arguments. For MCP, also obtain the copied server URL and approved tool schema described in [Run an approved MCP tool](#mcp-tools).

#### Developer

### 1. Prepare the unattended process

In Orchestrator, select the intended folder and verify the invoice-copy process under **Automations → Processes**. Its owner supplies the release GUID, folder ID and argument schema. Configure the unattended runtime, machine and execution account with the UiPath administrator; a Voiceflow tool does not provision a robot or start a customer's attended desktop session.

### 2. Define the business contract

For this recipe, accept string inputs `in_RequestId`, `in_CustomerId` and `in_InvoiceId`. Check the customer's invoice access before retrieving or creating a document, and deduplicate the stable request ID before side effects. Return `out_RequestId`, `out_Status` and `out_DocumentId` only after the approved document exists. Treat `out_Status: "ready"` as this process's business outcome. Adapt these example fields to your verified process schema.

### 3. Authorize the execution identity

Have the administrator authorize the identity for job creation and viewing in that folder. For the PAT connection used here, open your UiPath user menu → **Preferences → Personal access token → Generate new token**. Set its name and expiry, select Orchestrator scopes **OR.Execution** and **OR.Jobs**, and save the value once. Scopes and folder permissions both apply; a token does not grant access the user lacks. Keep a named rotation owner.

### 4. Verify the handoff in UiPath

Start one safe test in **Automations → Jobs**, inspect its inputs/output and compare its document with the source invoice. Verify the wrong customer/invoice pair is rejected without exposing a document. Copy the actual cloud base URL and folder ID; the folder's `fid` URL parameter identifies its numeric ID. Obtain the release key from the approved process's API record rather than guessing from its display name.

Provider setup: [Jobs and runtime ownership](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/about-jobs), [request URL and folder headers](https://docs.uipath.com/orchestrator/automation-cloud/latest/api-guide/building-api-requests) and [PAT permissions](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/authenticating-with-a-personal-access-token).

### Store the credential and request variables

#### Studio

In your test project, open **More → Secrets** and create `uipath_token` with the bearer token. Creating its default also writes Main's Published value; use a test project. Set the selected Environment's Draft override if it differs. In **More → Variables**, create `uipath_request`, `uipath_job_id` and `uipath_job_key` with empty defaults. Your application developer supplies the prepared request and clears the job variables before each new confirmed request.

#### Developer

Set `PROVIDER_CREDENTIAL` to the UiPath token. Create the credential and empty variables. Save the returned `secret.id` as `SECRET_ID` and each returned `variable.id`; the capture mapping below requires variable IDs, not names.

#### API

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"uipath_token",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

for name in uipath_request uipath_job_id uipath_job_key; do
  jq -n --arg name "$name" '{name:$name,color:"#515A63",defaultValue:""}' |
  curl --fail-with-body --silent --show-error \
    "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
    -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
done
```

#### CLI

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" \
  '{name:"uipath_token",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json

for name in uipath_request uipath_job_id uipath_job_key; do
  vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
    --name "$name" --color-param '#515A63' --default-value '""' --output-format json
done
```

Creating a Secret default also writes Main's Published value. If needed, set the selected Environment's [Draft override](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes) before testing. Design-time MCP discovery uses the project default.

<a id="robot-jobs"></a>

## Start and follow a robot job

Retain the new job reference and check its business output later.

Invoke **Generate an invoice copy** only after the customer confirms the invoice request and your application supplies a verified customer, invoice and stable request ID. Invoke **Check the invoice job** only for the job reference saved by that successful start. Bind credentials, the prepared request and job ID to trusted defaults. A new job with state `Pending` is a receipt, not a ready invoice. Use only the current job's output; explain pending or failure without reusing an older result or automatically repeating an uncertain write.

### Prepare the job request

#### Studio

Have your application developer deliver the encoded request described below and supply it as `uipath_request` on the next [runtime action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). Before a new confirmed request, clear `uipath_job_id` and `uipath_job_key`. For a Studio Run test, temporarily set the request variable's default to the developer-supplied test string; backend runtime variables do not populate Run. Clear it after testing.

#### Developer

Download [encode-request.mjs](/docs/examples/automation/encode-request.mjs). Build `uipath-request.json` in the authenticated application, using the fixed approved release and verified inputs. `InputArguments` is a JSON-serialized string inside the outer JSON object. Use a serializer for both layers:

```sh
jq -n --arg release "$RELEASE_KEY" --arg request "$REQUEST_ID" \
  --arg customer "$VERIFIED_CUSTOMER_ID" --arg invoice "$VERIFIED_INVOICE_ID" \
  '{startInfo:{ReleaseKey:$release,Strategy:"ModernJobsCount",JobsCount:1,
    InputArguments:({in_RequestId:$request,in_CustomerId:$customer,in_InvoiceId:$invoice}|tojson)}}' \
  > uipath-request.json
node encode-request.mjs uipath-request.json > uipath-payload.txt
```

Set these shell values from your verified test fixture; the model must not generate them. The encoder preserves literal braces, quotes and newlines through Voiceflow interpolation. Supply its string as `variables.uipath_request` with empty `variables.uipath_job_id` and `variables.uipath_job_key` on the next runtime action before starting a new request. Your application/process must enforce access and deduplication; descriptions are model guidance. UiPath limits process input arguments to 10,000 characters, including names and escaping.

### Create the start tool

#### Studio

### 1. Configure the request

Open **Agent → Global tools → + → API**. Name the tool **Generate an invoice copy**, select **POST** and enter your actual organization, tenant and fixed folder ID:

| Field | Value |
| --- | --- |
| URL | `https://cloud.uipath.com/ORG/TENANT/orchestrator_/odata/Jobs/UiPath.Server.Configuration.OData.StartJobs` |
| Header: Authorization | `Bearer {authorization}` |
| Header: X-UIPATH-OrganizationUnitId | Your fixed numeric folder ID |
| Header: Content-Type | `application/json` |
| Raw JSON body | `{payload}` |

Native API request editor for starting a UiPath job with a fixed folder and prepared body — Start one approved process with its prepared request.

### 2. Bind inputs and capture the new reference

On the attached tool, set `authorization`'s **Default value** to Secret `uipath_token` and `payload`'s **Default value** to variable `uipath_request`. Keep **Async execution** off to receive the start response. Under **Capture response**, add path `value[0].Id` to `uipath_job_id` and `value[0].Key` to `uipath_job_key`. These paths start at the provider body. Clearing the variables before a new start prevents an absent capture from leaving an earlier job reference.

### 3. Describe when it may run

Set **Trigger** to start only after the confirmed invoice request and trusted application inputs are ready. Tell the agent to retain the new job reference, report waiting when pending, and never claim the document is ready from this start receipt. Do not repeat a start after a timeout; investigate the original request first.

#### Developer

Save `uipath-start-tool.json`, replacing `ORG`, `TENANT` and the example folder ID with the administrator's fixed values:

```json
{
  "name": "Generate an invoice copy",
  "description": "Start the approved invoice-copy process for the confirmed, verified request.",
  "httpMethod": "post",
  "url": "https://cloud.uipath.com/ORG/TENANT/orchestrator_/odata/Jobs/UiPath.Server.Configuration.OData.StartJobs",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {authorization}"
    },
    {
      "key": "X-UIPATH-OrganizationUnitId",
      "value": "12345"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "type": "raw-input",
    "contentType": "json",
    "content": "{payload}"
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-start-tool.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-start-tool.json
```

Save `apiTool.id` as `START_TOOL_ID`. Discover its input IDs and schema:

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$START_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$START_TOOL_ID" --output-format json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$START_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$START_TOOL_ID" --output-format json
```

Match each `variables[].name` to its `id` and resolve `unresolvedReferences`. Prepare a standalone test body:

```sh
jq -n --rawfile payload uipath-payload.txt \
  '{inputs:{authorization:"{uipath_token}",payload:$payload}}' > uipath-start-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$START_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-start-inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$START_TOOL_ID" --output-format json < uipath-start-inputs.json
```

This call starts a real test job. Require `success: true`, HTTP 200 in `output.status` and exactly one new job in `output.body.value` with its numeric `Id`, GUID `Key` and state. Treat `truncated: true` as incomplete. Record the tuple with the verified request/customer/invoice in your application before cross-session use. Do not retry an ambiguous creation; inspect UiPath Jobs and process logs with the original request ID.

Save `uipath-start-attachment.json`, substituting the discovered tool/input IDs and the variable IDs returned at creation:

```json
{
  "type": "api",
  "apiToolID": "YOUR_START_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Use Generate an invoice copy only after confirmation and verified application inputs. The new job reference is a receipt, not a ready document. Explain pending or failure from the current result; never repeat an uncertain start.",
  "asyncExecution": false,
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{uipath_token}"
    },
    "payload": {
      "apiToolInputVariableID": "PAYLOAD_INPUT_ID",
      "required": false,
      "defaultValue": "{uipath_request}"
    }
  },
  "captureResponse": {
    "job-id": {
      "path": "value[0].Id",
      "variableOrEntityID": "JOB_ID_VARIABLE_ID"
    },
    "job-key": {
      "path": "value[0].Key",
      "variableOrEntityID": "JOB_KEY_VARIABLE_ID"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-start-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-start-attachment.json
```

Standalone execution does not apply an agent attachment's captures. The attached API tool exposes the provider body, so the capture path is `value[0].Id`, not `output.body.value[0].Id`. If a path is absent, a previous variable value can remain; clear both job variables before a new confirmed request and require a successful current start before status lookup.

### Check the job and document

The start response's numeric `Id` identifies the OData job resource; its `Key` is a separate GUID. Retrieve one job to inspect output arguments. The Jobs collection response omits `InputArguments` and `OutputArguments`, even when a list query selects them.

#### Studio

Create another API tool named **Check the invoice job** with **GET** and URL `https://cloud.uipath.com/ORG/TENANT/orchestrator_/odata/Jobs({job_id})`. Use the same fixed folder header and `Authorization: Bearer {authorization}`. Bind `authorization` to `uipath_token` and `job_id` to `uipath_job_id`; keep **Async execution** off. Do not collect a job ID from the customer or allow a status lookup when the current start failed or the saved ID is empty.

Set **Trigger** to check only this customer's saved invoice job when they ask for its progress. Require matching `Id`/`Key` and request context. UiPath returns `OutputArguments` as a JSON string: your application/process owner must verify its decoded fields. Report the invoice ready only when the current job is `Successful`, `out_RequestId` matches this request, `out_Status` is `ready` and `out_DocumentId` identifies the authorized document. Deliver it through your application's approved document route.

#### Developer

Save `uipath-status-tool.json` with the same actual cloud URL and folder:

```json
{
  "name": "Check the invoice job",
  "description": "Check only the saved job belonging to this verified invoice request.",
  "httpMethod": "get",
  "url": "https://cloud.uipath.com/ORG/TENANT/orchestrator_/odata/Jobs({job_id})",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {authorization}"
    },
    {
      "key": "X-UIPATH-OrganizationUnitId",
      "value": "12345"
    }
  ]
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-status-tool.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-status-tool.json
```

Save `apiTool.id` as `STATUS_TOOL_ID`. Repeat the input-list operation above with this ID, then inspect its schema:

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$STATUS_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$STATUS_TOOL_ID" --output-format json
```

Save the new `authorization` and `job_id` input IDs. For a standalone lookup, set `JOB_ID` to the numeric Id from the successful test start and create the execution body:

```sh
jq -n --arg job "$JOB_ID" \
  '{inputs:{authorization:"{uipath_token}",job_id:$job}}' > uipath-status-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$STATUS_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-status-inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$STATUS_TOOL_ID" --output-format json < uipath-status-inputs.json
```

Require `success: true`, HTTP 200 and a complete `output.body` matching the saved Id/Key. Decode the JSON string `output.body.OutputArguments` before checking its business fields. A `Successful` job alone does not prove the document exists; a soft-stopped job can also reach that state. Require the matching `out_RequestId`, `out_Status: "ready"` and authorized `out_DocumentId`. A missing, invalid or mismatched output is unconfirmed, not success.

Save `uipath-status-attachment.json` with this tool's discovered IDs:

```json
{
  "type": "api",
  "apiToolID": "YOUR_STATUS_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Use Check the invoice job when the customer asks for progress and the application has supplied their saved job reference. Check the current job identity and decoded output. Report ready only for a successful job with matching request and ready document output; otherwise explain pending or failure. Never start a replacement job automatically.",
  "asyncExecution": false,
  "inputVariables": {
    "authorization": {
      "apiToolInputVariableID": "STATUS_AUTHORIZATION_INPUT_ID",
      "required": false,
      "defaultValue": "{uipath_token}"
    },
    "job_id": {
      "apiToolInputVariableID": "JOB_ID_INPUT_ID",
      "required": false,
      "defaultValue": "{uipath_job_id}"
    }
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-status-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-status-attachment.json
```

For later sessions, your backend stores the job/request/customer mapping and authorizes access before supplying the saved job ID/Key on the next runtime action. This page's direct-tool recipe retains variables within the current conversation; it does not provide a durable job store, polling scheduler or notification delivery. Build those in your existing application when needed.

`Pending`, `Running` and `Suspended` mean the invoice is not confirmed ready. `Faulted` or `Stopped` require investigation. Wait between status requests; do not loop repeatedly within one agent turn. Voiceflow does not manage the robot, wait indefinitely for it or automatically reopen a closed conversation when it finishes.

### Test the conversation

#### Studio

In **Run**, supply the isolated test request and empty job variables, then ask **Please generate a copy of my invoice** and confirm it. Inspect the start tool's current response and saved job ID/Key. Ask **Is my invoice ready?**, inspect the status tool and compare the answer with UiPath **Jobs** and the actual document. Also test pending, faulted and rejected-customer cases. The agent must not report ready from the receipt or use an older job after a failed new start.

#### Developer

Use a test client bound to this project's Draft. Supply the encoded request and empty job variables on its runtime action, ask for the invoice copy and confirm it. Inspect the emitted tool call, current result and captures; ask for progress and verify the saved job is used. Compare the answer with UiPath Jobs and the document. Test pending, faulted, unauthorized invoice and missing capture cases; no ready claim or automatic resubmission is valid for those outcomes. Standalone execution alone does not verify this conversation path.

Provider contracts: [StartJobs and job response](https://docs.uipath.com/orchestrator/automation-cloud/latest/api-guide/jobs-requests), [modern folder job strategy](https://docs.uipath.com/add-ins/other/latest/user-guide/mulesoft-quickstart), [single-job output retrieval](https://docs.uipath.com/orchestrator/automation-cloud/latest/api-guide/rate-limits) and [job states](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/job-states).

<a id="mcp-tools"></a>

## Run an approved MCP tool

Connect a UiPath-hosted server and select its verified business tool.

Invoke the approved order-lookup tool when the customer asks **Where is my order?** and the authenticated application supplies the verified request. Bind its input to the prepared variable; the model must not choose another customer's identity or collect credentials. Use the current tool's business response, checking its order and status. An MCP success can contain pending work or a business error; explain that result without claiming completion, reusing an earlier result or automatically repeating a write.

### Prepare the hosted MCP server

#### Studio

Ask your UiPath owner to create a **UiPath** MCP server in the intended Orchestrator folder and expose only the approved read-only order-lookup process. Obtain the copied URL, exact tool name, discovered input schema and verified success/error examples. This recipe uses one string process input for a prepared JSON request; your owner must confirm how that argument appears in the actual MCP schema.

Use the PAT from the connection section with **OR.Execution**, **OR.Jobs** and a folder role granting **MCP Servers → View**. Direct **Integration Service activity** tools do not support PAT authentication; listing them does not make them executable with this connection.

#### Developer

In the intended Orchestrator folder, open **MCP Servers → Add MCP Server**, select **UiPath**, enter a name and description, then **Add Tool** and select the approved process. For this read-only recipe, its owner defines one string argument containing `customer_id` and `order_id`, validates access and returns that order's status and estimated delivery. Select **Add**, confirm the server appears in **MCP Servers**, then copy its URL; do not assemble its folder path by hand. UiPath hosts this server and executes its artifacts.

The user behind the PAT needs **MCP Servers → View** in this folder, plus **OR.Execution** to list tools and **OR.Jobs** to execute. Direct Integration Service activity tools need a different supported authentication flow and cannot run under this PAT recipe. Voiceflow's URL/header setup below does not perform UiPath's interactive OAuth flow.

Provider setup: [Create a UiPath MCP server](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/creating-uipath-mcp-servers), [PAT requirements](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/authenticating-with-a-personal-access-token) and [MCP server types](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/mcp-server-types).

### Register and inspect the server

#### Studio

Open **Agent → Global tools → + → MCP → Create MCP tool**. Name it **UiPath**, paste the actual URL supplied by your owner and add `Authorization` with `Bearer {uipath_token}` as a Secret reference. Select **Add MCP server**, then select only the approved order-lookup tool. Inspect its actual input field; tool names and argument names come from that server.

Native Add MCP server dialog with the UiPath URL and Secret-backed Authorization header — Use the copied UiPath MCP URL and the authorized identity.

#### Developer

Save `uipath-server.json`, replacing the illustrative URL with the copied server URL. The Secret must already exist; its project default supplies design-time discovery.

```json
{
  "name": "UiPath",
  "url": "https://cloud.uipath.com/ORG/TENANT/agenthub_/mcp/FOLDER/SERVER",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer {uipath_token}"
    }
  ]
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/mcp-server?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-server.json
```

#### CLI

```sh
vf mcp-server create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-server.json
```

Save `mcpServer.id` as `SERVER_ID`. Discover its tools, select the approved one from `mcpTools` and save its `id` as `MCP_TOOL_ID`:

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&serverID=$SERVER_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf mcp-tool list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --server-id "$SERVER_ID" --output-format json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"
```

#### CLI

```sh
vf mcp-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json
```

Read `inputSchema`. For this recipe, confirm it exposes one required string argument for the prepared request, and set `MCP_INPUT_NAME` to that actual field name. If the schema differs, map and verify it with the process owner before continuing; no universal UiPath tool or argument name is assumed.

### Supply trusted inputs and use the result

#### Studio

In **More → Variables**, create `uipath_mcp_request` with an empty default. Have the application developer prepare the literal-safe JSON request string described below and supply it on the next runtime action. Bind the approved tool's request input **Default value** to that variable. Set **Trigger** to use the order lookup for **Where is my order?** and report only its current verified result; explain missing, failed or pending work truthfully.

In **Run**, temporarily use the developer's verified test string as this variable's default, ask **Where is my order?** and inspect the actual tool call, response and answer. Compare the order/status with UiPath job history and the source system. Test a rejected customer/order too; the agent must not expose another customer's data or reuse an earlier result. Clear the test default afterward.

#### Developer

Save the application's verified `customer_id` and `order_id` in `uipath-mcp-request.json`. This is your process's example input contract, not a built-in UiPath payload. Use [encode-request.mjs](/docs/examples/automation/encode-request.mjs) to preserve literal text:

```sh
node encode-request.mjs uipath-mcp-request.json > uipath-mcp-payload.txt
jq -n --arg name "$MCP_INPUT_NAME" --rawfile payload uipath-mcp-payload.txt \
  '{inputs:{($name):$payload}}' > uipath-mcp-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/mcp-tool/$MCP_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-mcp-inputs.json
```

#### CLI

```sh
vf mcp-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$MCP_TOOL_ID" --output-format json < uipath-mcp-inputs.json
```

Require `success: true`, inspect `output` and reject provider `isError` results. Interpret actual text blocks/structured content against the verified response; do not assume every tool returns the same envelope. Require this order's business status and required fields. A pending receipt is not a completed result, and `truncated: true` is incomplete.

Create the empty `uipath_mcp_request` variable using the variable-create operation above and have the authenticated backend supply it on the next runtime action. Build `uipath-mcp-attachment.json` using the actual argument name and discovered tool ID:

```sh
jq -n --arg tool "$MCP_TOOL_ID" --arg name "$MCP_INPUT_NAME" \
  '{type:"mcp",mcpToolID:$tool,target:{global:true},
    description:"Use for Where is my order? with verified application inputs. Check only the current business response; explain missing, pending or failed results without claiming completion or repeating an uncertain write.",
    inputVariables:{($name):{mcpIntegrationVariableName:$name,required:false,
      defaultValue:"{uipath_mcp_request}"}}}' > uipath-mcp-attachment.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @uipath-mcp-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < uipath-mcp-attachment.json
```

Use a test client bound to this project's Draft, supply `variables.uipath_mcp_request` on its next runtime action, and ask **Where is my order?**. Inspect the emitted call, current result and agent answer against UiPath's history and source order. Test a rejected-resource/provider-error case; the agent must not claim success or reuse an older response. Registration and standalone execution do not verify this conversation path.

<a id="maintaining-the-connection"></a>

## Maintaining the connection

Inspect provider execution, update credentials and test the intended deployment.

| Symptom | Check |
| --- | --- |
| 401/403 | Check token expiry, Orchestrator scopes, user activation and folder permissions. A scope alone does not grant the folder role. |
| Job remains Pending | Inspect UiPath Jobs and unattended runtime, machine/account availability and capacity with its owner. |
| Successful job, no document | Decode the current output and validate the request ID and business outcome; job state alone is insufficient. |
| Missing output from a Jobs list | Retrieve the single saved job resource rather than the collection. |
| MCP tool lists but fails | Check execution permissions and artifact type. Direct Integration Service activity tools do not support this PAT connection. |
| Timeout or missing new job ID | Inspect the original request in UiPath Jobs/logs and the document system before retrying. StartJobs does not supply this recipe with automatic business deduplication. |

### Replace a credential

### 1. Inspect the original provider execution

Use the request ID, saved job Id/Key and execution time to find the UiPath job and its document. A timeout can follow a completed side effect; reconcile that state before repeating a write.

### 2. Update the intended credential version

#### Studio

Open the same project and **More → Secrets**, select the UiPath Secret and update the target Environment's **Draft value** for testing. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### Developer

Retain `secret.id` from creation as `SECRET_ID`, set `PROVIDER_CREDENTIAL` to the replacement and use the value operation below. After validation, explicitly set the Published value for the intended Environment; this changes the credential serving live traffic.

#### Developer

Save the Draft update body as `credential-value.json`:

```sh
jq -n --arg value "$PROVIDER_CREDENTIAL" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' > credential-value.json
```

#### API

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @credential-value.json
```

#### CLI

```sh
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" \
  --output-format json < credential-value.json
```

For the selected Environment's Published credential, change `versionVariant` to `published` after the Draft test. To replace the project default, omit `environmentAlias` and `versionVariant`; this also writes Main's Published value. Test the intended connection before changing a live default.

Before launch, select the target Environment and supply the UiPath Secret's **Default value** for its published agent; a Draft override alone does not supply Published. [Publish the tested configuration](/docs/documentation/deploy/environments/publishing), then repeat the conversation test against that Environment's published client and verify the provider account/resource it reaches.

After a process release, argument or MCP catalog change, inspect the new schema, rebind inputs and rerun success/error conversation tests. Rotate the credential with the UiPath owner, update the relevant Secret default/Environment overrides, and retest the existing tool. Removing a tool from Voiceflow does not remove the UiPath process/server or revoke its credential. Disable/revoke access in UiPath when retiring the integration, then remove the unused attachment and API resource.
