uipath-mcp-servers

UiPath Agent Gateway MCP Servers

Agent Gateway is Orchestrator's hub for MCP servers and A2A agents: about, MCP server types. This skill covers its MCP servers. The CLI group is named agenthub: uip agenthub mcp manages servers, uip agenthub mcp-tools manages their tools.

When to Use This Skill

Servers — uip agenthub mcp, plus uip agenthub platform-services / platform-tools to look up platform names:

• Create, update, delete, list or get an MCP server of any type (Server Types says when to use each), and refresh its tools.
• Check whether a server works: its Integration Service connection and its tools (Checking a Server).
• Get the McpUrl an MCP client connects to.
• Find the UiPath services and tool names a platform server can expose.

Tools — uip agenthub mcp-tools:

• Bind Orchestrator processes, agents, agentic processes or API workflows as tools on a uipath server; edit or remove those tools.
• Add or remove tools on a platform server.
• List or get the tools of any server.

Not this skill: an agent that calls MCP tools → uipath-agents; running the uip CLI itself as an MCP server (uip mcp serve) → uipath-platform; A2A agents (uip agenthub remote-a2a-agent --help; no skill covers them). No skill covers writing the MCP server itself (uipath-mcp Python SDK, FastMCP, self-hosted runtime): see the uipath-mcp quick start.

Critical Rules

These are the things the CLI does not advertise in --help.

1. Pass slugs exactly as mcp list prints them. On create the CLI does not validate the slug: without --slug it sends --name lowercased with other characters turned into -, which can still be under 3 or over 50 characters. The service requires ^[a-z0-9-]+$, 3-50 characters (display name 3-100), so always pass --slug. The service reads a server by display name before slug, so mcp get, mcp update, refresh-tools and every mcp-tools ... --mcp refuse an argument that reads back another slug ('<INPUT>' resolves to the MCP server '<SLUG>' …). Never pass a display name or a GUID: mcp delete returns 404 for anything but the slug.

2. Give every server command its folder. Pass --folder-key <FOLDER_KEY> (a GUID) or --folder-path <FOLDER_PATH> (a name or Parent/Child), never both, as Folder Context lists per command. A 404 on a slug usually means the wrong folder: find the server with mcp list --all-folders and pass its FolderKey.

3. Payloads are camelCase; everything else the CLI prints is PascalCase. --file / --body keys must be the API's camelCase names (name, slug, uri, headers, processKey, targetIdentifier, …). mcp create, mcp update and the mcp-tools create / update verbs refuse a key that names a field in another case, also with --dry-run (Payload keys differ from their fields only in case: `Name` should be `name`, …): rename each key as listed. A key that names no field is dropped without an error. mcp template and mcp-tools template print a camelCase payload: edit it and send it as it is. --print-schema describes the payload in camelCase; it is not one. mcp get, mcp list, every create / update result, mcp-tools list and the --dry-run plan print PascalCase: put a copied value under the camelCase name --print-schema gives. mcp get also shows a remote server's URI as Arguments and remote / swagger headers as EnvironmentVariables.

4. Set headers and environment variables with the flags. Use --header <NAME>=<VALUE> on remote / swagger and --env <KEY>=<VALUE> on command, once per entry, on create and update. The CLI sends the newline-separated Name:Value / KEY=VALUE lines the service stores and refuses a repeated name or a value with a line break. A header value of exactly %ASSETS/<ASSET_NAME>% is replaced at call time by that Orchestrator asset's value, read from the server's folder. The asset must hold the whole value (e.g. Bearer <TOKEN>): Bearer %ASSETS/<ASSET_NAME>% is sent literally. Do NOT invent another syntax. Orchestrator gives the asset's value to Agent Gateway in the portal and to jobs, but not for a CLI login: refresh-tools from the CLI on such a server fails with 403 (troubleshooting). On mcp update, --header / --env replace every stored entry; keep a secret by passing "<NAME>=****" with the name spelled exactly as mcp get shows it with a **** value.

5. Confirm each mutation from its result. mcp create / mcp update return the stored server, mcp-tools create-resource / create-raw / update the stored tool, and delete reports Deleted: true only after every delete succeeded. mcp-tools enable / disable return the server without its selection: confirm with uip agenthub mcp-tools list --mcp <SLUG> --folder-path <FOLDER_PATH> --limit 1000 --output-filter "{Names: Items[].Name, Total: Total, Count: Count}" --output json (unfiltered rows carry each tool's schemas). mcp get shows secrets as **** either way, so it cannot prove a masked value was kept. refresh-tools is confirmed by its Data.Status (Rule 7), not by re-listing tools.

6. Scalar flags keep; a payload replaces. With scalar flags, mcp update reads the server and sends back every stored field you do not change. A --file / --body payload is sent as it is: each field it leaves out is kept or cleared as the payload table says. An omitted description is always cleared, and a platform payload without selectedToolNames / useAllTools clears the selection and turns All tools off; --print-schema does not say this for every field. On a uipath server, an update without tools keeps every tool; a payload with tools replaces them all. Read Updating Servers before any mcp update.

7. refresh-tools depends on the server type. A new coded, command or remote server has no tools until it runs: run it after mcp create, and after a remote --uri change (the stored tools still come from the old URI). It needs the folder, also with --dry-run.

   • coded / command: Data: {RuntimeId, Status: "Started"}. Agent Gateway started the server as an Orchestrator job (uip or jobs get <RUNTIME_ID> --output json); the tool list changes only when that job registers its tools. Report the RuntimeId; never claim the tools are refreshed.
   • remote / swagger: Data: {Status: "Refreshed"}, and the tools are already stored: remote tools are fetched from its URI; swagger tools are regenerated from its swaggerUrl, downloaded again with the stored headers (or from the stored spec when it has no URL).
   • platform: Data: {Status: "Refreshed"}. The service drops its cached service definition; the selection is kept.
   • uipath / selfhosted: refused. uipath tools come from mcp-tools create-resource; selfhosted tools from the runtime that serves it.

8. Deletes take a slug, the folder and --yes. mcp delete and mcp-tools delete refuse to run without --yes, also with --dry-run, and never prompt: confirm with the user before passing it. List what you will delete first (mcp list --limit 1000, Total equal to Count; a prefix is --output-filter "Items[?starts_with(Slug, '<PREFIX>')].Slug"), show each slug with its Name, and delete only the servers the user confirmed from that list. mcp delete takes one slug per call: run it for each, then list again. mcp delete --dry-run does not check that the server exists. mcp-tools delete --name <SUBSTR> matches by case-insensitive substring; when several tools match, the one named exactly that wins, and --allow-multiple deletes every match: prefer tool ids from mcp-tools list.

9. List platform names; never guess them. Take --service from platform-services list and --tool from platform-tools list, exactly as cased, one name per --tool flag (the platform steps). Services differ per environment: never assume orchestrator. Pass --tool or --use-all-tools, not both; with neither, the server has no tools.

10. Never route stored credentials around a refusal. mcp update refuses to move a remote server to another origin (scheme, host or port), or a swagger server to another spec, while that would send its stored connection token or secret headers there. Follow the refusal's Instructions (moving a server); do not delete headers or connections to get past it without the user's consent.

Folder Context

Command	Folder input
mcp list	one of --folder-key, --folder-path, --all-folders, required
mcp get, mcp create <TYPE>, mcp update (incl. --print-schema, --dry-run), mcp delete, mcp refresh-tools	--folder-key or --folder-path, required
every mcp-tools verb that takes --mcp	the server's folder, required; create-resource, create-raw and update also take --target-folder-key / --target-folder-path for a target in another folder
mcp-tools candidates	optional: tenant-wide without one
mcp create <TYPE> --print-schema	none (folder flags are ignored)
mcp template, mcp-tools template, platform-services list, platform-tools list	none: a folder flag fails as unknown option

• Find folders with uip or folders list --output json: pass a row's Key as --folder-key or its Path as --folder-path.
• Personal workspace folders (<USER_EMAIL>'s workspace) do NOT resolve by name: use --folder-key.
• A name shared by nested folders resolves to the folder whose full path matches exactly; otherwise the CLI lists the candidates: re-run with Parent/Child or --folder-key.
• mcp list --all-folders lists the servers in every folder you can read, each row with its FolderKey (mcp-tools has no --all-folders). Folders it cannot read are reported only on stderr.
• A scalar create coded fills the payload's folderKey from either folder flag; a coded --file / --body must carry folderKey itself.

Trust the CLI

• uip agenthub mcp create <TYPE> --print-schema --output json — create payload fields per type. No login, no folder.
• uip agenthub mcp template <TYPE> --output json — create --file skeleton: edit the values, send it as it is.
• uip agenthub mcp update <SLUG> --folder-path <FOLDER_PATH> --print-schema --output json — update fields for that server's type. It reads the server, so it needs a login, the folder and the exact slug. Only some fields say what leaving them out does: the payload table covers every one.
• platform names come from uip agenthub platform-services list and uip agenthub platform-tools list: run them as the platform steps give them.
• uip agenthub mcp-tools candidates --category <CATEGORY> --output json — Orchestrator resources that can become tools on a uipath server. <CATEGORY> ∈ automation | agent | agentic-process | api-workflow; --category exists only for uipath server tools (candidates, create-resource, create-raw).
• uip agenthub mcp get <SLUG> --folder-path <FOLDER_PATH> --output json — McpUrl is the endpoint an MCP client connects to. To show a server the user names, find its Slug by Name in mcp list, then mcp get it and list its tools (Rule 5).
• mcp get / mcp list print Type as a number: 0 uipath, 1 command, 2 coded, 3 selfhosted, 4 remote, 6 platform, 7 swagger. Status 1 is connected, 0 disconnected. A tool's Type is a different number. Null fields are left out: no ConnectionId means no Integration Service connection. On a swagger server mcp get also prints the spec URL (SwaggerUrl, left out for an inline spec); when it cannot read it, it warns on stderr ([WARN] Could not read the spec URL …) and shows the server without it.
• --output-filter <JMESPATH> works on every command, over the keys it prints: PascalCase (Items[].Slug), camelCase on mcp template and --print-schema (uri). The result is cased the same way, so a filter cannot turn output into payload keys. mcp list and mcp-tools list filter only the current page (default --limit 50): pass --limit 1000 and check that Total equals Count. platform-services list / platform-tools list refuse a filter without --limit.
• --dry-run runs the CLI's checks and prints the plan (Code: DryRun) without the mutation. mcp update, refresh-tools and mcp-tools mutations still read the server (login, exact slug, folder), and every mcp update refusal fires in a dry run too. The service's validation never runs, so a clean dry run does not guarantee the real call succeeds.
• A failure prints ErrorCode, Retry, Message, Instructions, and when they apply NextCommand (values shell-quoted), Errors (fields a 400 rejected) and Context.HttpStatus. Act on ErrorCode, Retry and Instructions, not on the exit code. NextCommand usually repeats your folder flag, but some name only the verb (mcp-tools enable --mcp <SLUG> on a platform server, mcp-tools create-resource --mcp <SLUG> --folder-key <GUID> on a uipath one): add the folder and the required flags before running it.
• Most --help examples omit the folder flag (mcp delete --dry-run also omits --yes, the mcp-tools update examples omit --mcp), and their output keys are cased differently from the real output: take casing from Rule 3, not from the examples.

Server Types

uip agenthub mcp create <TYPE> shares --name, --slug, --description, --version, --file / --body / --print-schema, --dry-run, --folder-path / --folder-key, --login-validity. Use exactly one of scalar flags, --file or --body. The CLI checks no required field (--print-schema lists them); the service answers 400 with Errors, except a swagger create with neither --spec-url nor swaggerContent, which fails with HTTP 409 Either SwaggerUrl or SwaggerContent must be provided.

Type	Type-specific flags	When to use	Tools from	More in
uipath	(none)	A server you fill with tools that run Orchestrator processes, agents, agentic processes or API workflows.	mcp-tools create-resource	Tools, binding, uipath updates
coded	--process-key <PROCESS_KEY>	A published coded MCP server package (uipath-mcp Python SDK; process type MCPServer), started as a job in the server's folder. Not a coded agent.	refresh-tools (async)	payload, refresh errors
command	--command <CMD>, --arg <ARG> (repeatable, at least one), --env <KEY>=<VALUE> (repeatable)	A stdio MCP server Agent Gateway starts as a command (npx / uvx + package) in a serverless job.	refresh-tools (async)	masked values, refresh errors
remote	--uri <URL>, --header <NAME>=<VALUE> (repeatable), --connection-id <CONNECTION_ID>, --use-relay	An HTTP MCP server hosted elsewhere: a vendor's, or one inside the company network through Relay.	refresh-tools (sync)	masked values, moving a server, network errors
swagger	--spec-url <URL>, --header <NAME>=<VALUE> (repeatable), --use-relay	A REST API with an OpenAPI document: one tool per operation.	the spec, on create and refresh-tools (sync)	payload, moving a server, network errors
platform	--service <SERVICE_NAME>, then --tool <TOOL_NAME> (repeatable) or --use-all-tools	A first-party UiPath service (e.g. Test Manager): a chosen tool set, or every tool including ones added later.	the selection, or All tools	platform selection, platform errors

• coded: --process-key is the process (release) Key GUID from uip or processes list --folder-key <FOLDER_KEY> --process-type MCPServer --output json, not its ProcessKey field (the package name). The process must be in the server's folder, and the service does not check it on create: a wrong key surfaces only when the server runs. mcp template coded has placeholder processKey / folderKey: replace both with GUIDs.

• command: the service splits arguments on spaces, so one --arg value cannot contain a space.

• remote / swagger: without --use-relay the service blocks private hosts (URL blocked for security reasons: …); with it, any absolute http(s) URL is reached through Relay (swagger: the spec download and the API calls). On mcp update, --use-relay / --no-use-relay switch Relay; without either the setting is kept. --connection-id (remote) is the GUID of an Integration Service connection whose token authenticates the calls: an OAuth connection of connector uipath-uipath-mcp, from uip is connections list <CONNECTOR_KEY> --all-folders --output json with that connector key.

• swagger: needs the tenant's Swagger MCP feature (otherwise HTTP 404). --header values go with the spec download and every API call. An inline spec (swaggerContent) goes only in --file / --body. --filter is accepted but not sent. The create result includes the whole spec: filter it (--output-filter "{Slug: Slug, McpUrl: McpUrl}").

• platform:

  1. uip agenthub platform-services list --output json — match the user's wording to DisplayName; pass its ServiceName. Several names can share the words (Test Manager, Test Manager External, Test Manager Performance Testing): take the exact match, otherwise ask.
  2. uip agenthub platform-tools list --service <SERVICE_NAME> --limit 1000 --output-filter "{Names: Items[].Name, Total: Total}" --output json — the tool names. Unfiltered rows carry JSON Schemas and run to hundreds of KB; --name <SUBSTR> searches and returns full rows with Description. Read the Description of each candidate before picking tools for a request ("list test cases": Get_test_cases, not Get_Automated_Test_Cases_For_Folder), and tell the user the exact names you picked.
  3. uip agenthub mcp create platform --name <NAME> --slug <SLUG> --service <SERVICE_NAME> --tool <TOOL_NAME> --tool <TOOL_NAME> --folder-path <FOLDER_PATH> --output json, or --use-all-tools instead of --tool.
  4. uip agenthub mcp-tools list --mcp <SLUG> --folder-path <FOLDER_PATH> --limit 1000 --output-filter "{Names: Items[].Name, Total: Total, Count: Count}" --output json — the tools it exposes (on an All tools server, every tool of the service).

  mcp get shows the service as Arguments and the mode as UseAllTools. Without Platform MCP on the tenant the two lists fail with Platform MCP is not enabled on this tenant., while create platform and a platform mcp update return a bare HTTP 404.

• selfhosted / process-assistant: mcp template accepts both, but mcp create has no such type. A self-hosted server registers itself when the uipath-mcp Python runtime starts; the CLI can list / get / delete it and refuses mcp update and refresh-tools on it. process-assistant is a legacy value.

Updating Servers

mcp update <SLUG> reads the server, then sends that type's full update body. Scalar flags change only what they name and cannot be combined with --file / --body; a payload keeps or clears what it leaves out as the payload table says, in camelCase, without type. Every type takes --name, --description and --version. A flag the type does not take is refused (<FLAGS> apply only to <TYPES> servers; '<SLUG>' is a <TYPE> server., applies after a single flag), and so is --service.

Type	Change it with
uipath	No other flag; the tools are kept. Change tools with mcp-tools: a payload tools list replaces them all (guide).
coded	--process-key; folderKey stays the server's own folder.
command	--command, --arg (replaces all arguments), --env (replaces all variables; Rule 4).
remote	--uri, --header (replaces all; Rule 4), --use-relay / --no-use-relay, --connection-id <CONNECTION_ID> or --clear-connection (with neither, the connection is kept).
swagger	--spec-url (downloads the spec again, regenerates the tools), --header (replaces all), --use-relay / --no-use-relay.
platform	--tool (replaces the whole selection), --use-all-tools / --no-use-all-tools; without them the selection and mode are kept. On an All tools server, --tool needs --no-use-all-tools.
selfhosted, process-assistant	Refused.

Payload fields per type, the uipath tools list, masked values and moving a server to another host: references/updating-servers-guide.md.

Checking a Server

Agent Gateway's Check connection tests a server's Integration Service connection; Refresh tools tests the server itself.

• The connection: uip is connections ping <CONNECTION_ID> --force-refresh --output json, with the ConnectionId from mcp get (no ConnectionId means the server has no connection to check). Data.Status: "Enabled" means it is active. Any other status fails with Connection '<CONNECTION_ID>' is not enabled (status: <STATUS>).; an Expired connection needs its owner to sign in again (uip is connections edit <CONNECTION_ID>, or Integration Service in the portal). Tell the user; do not create, swap or clear a connection to get past it.
• The server: refresh-tools (Rule 7). On remote and swagger, Refreshed means Agent Gateway reached the server (or the spec) with its credentials and stored the tools it listed; confirm with mcp-tools list (Rule 5). A failure names the cause (troubleshooting). On coded / command it only starts the job. It authenticates with the caller's own per-user connection on the server when there is one, otherwise with the server's ConnectionId; the CLI cannot list per-user connections.
• refresh-tools is a write: on remote and swagger, a tool list that differs from the stored one in any field recreates every tool with a new id and deletes the tools' guardrails. When the user only asked to check the server, say so before running it.

Tools (uip agenthub mcp-tools)

Verb	Works on
create-resource, create-raw, update, delete	uipath servers only
enable, disable	platform servers only
list, get --name <NAME>	every type
get <TOOL_ID>	every type except platform (404: its tools are not stored)
template, candidates	no server needed

• Bind a resource: pick a row from mcp-tools candidates --category <CATEGORY> --name <SUBSTR> --output json (one page, default 50: narrow with --name; show the row's Folder.Name next to its Name), then uip agenthub mcp-tools create-resource --mcp <SLUG> --name <NAME> --description "<DESCRIPTION>" --category <CATEGORY> --target-identifier <RESOURCE_ID> --target-folder-key <RESOURCE_FOLDER_KEY> --folder-path <FOLDER_PATH> --output json, with the row's Id and Folder.Key. Always pass --description (the service requires one; when the row has none, write one from the request) and --category. candidates --name matches substrings (EchoAgent also finds Coded copy of EchoAgent): take the row whose Name matches exactly, and when none or several do, show each Name with its Folder.Name and ask. A wrong row still creates a working tool, so check that the result's TargetIdentifier is the row's Id.
• Platform selection: uip agenthub mcp-tools enable / disable --mcp <SLUG> --name <TOOL_NAME> --folder-path <FOLDER_PATH> --output json (repeat --name) add or remove those tools and keep the rest. On an All tools server enable changes nothing and disable is refused: run uip agenthub mcp update <SLUG> --no-use-all-tools --folder-path <FOLDER_PATH> --output json first, which keeps every tool selected. disable refuses a name the service does not define (Tools not found in the <SERVICE_NAME> service: …), but one the service defines and the server does not select succeeds and changes nothing: list the tools first, and when the name is not among them, tell the user instead of running it.
• Edit a tool: a tool's own fields change with mcp-tools update <TOOL_ID>; mcp update changes the server's. Take the id from mcp-tools list: --name matches substrings, and when several match, the tool named exactly that (case-sensitive) wins. Only uipath tools can be edited: the tools of every other type come from their source (URI, spec, command, package, service), and refresh-tools rebuilds them from it.
• mcp-tools template prints a camelCase payload (Rule 3); create-raw ignores its scalar flags, so use it only with --file / --body. mcp-tools update --rename changes Name, not McpName, the name MCP clients see.

Flags, defaults, target folders, update, delete, get and paging: references/tools-guide.md. Most of it is for uipath and platform servers; for the other types only its listing section applies.

Troubleshooting

• Payload keys differ from their fields only in case: … — rename each key as listed (Rule 3); keys copied from mcp get or mcp-tools list are PascalCase. HTTP 400 on create-resource without --description — pass --description.
• AgentHub requires a folder context. … — add a folder flag (Folder Context). No folder named '<NAME>' was found. — a typo, or a personal workspace: pass its Key as --folder-key.
• '<INPUT>' resolves to the MCP server '<SLUG>', … — pass the stored <SLUG> (Rule 1); if <INPUT> is another server's slug, rename <SLUG> first. HTTP 404 on a slug — wrong folder, or not the slug (Rules 1, 2).
• --uri moves '<SLUG>' to another origin, … / --spec-url gives '<SLUG>' a new spec, … (or The payload's … for a --file / --body) — Rule 10.
• This command requires a <EXPECTED_TYPE> MCP server; <SLUG> is <TYPE>. — the mcp-tools verb does not apply to that type. On coded / command / remote / swagger, run the NextCommand (refresh-tools). On platform, its NextCommand names mcp-tools enable without --name or the folder: add both.
• Platform MCP is not enabled on this tenant., or HTTP 404 on create platform — the feature is off on this tenant: use another tenant or server type.

Reference Navigation

• references/updating-servers-guide.md — payload fields per type, uipath server updates, masked values, moving a server to another host.
• references/tools-guide.md — mcp-tools on uipath servers (bind, update, delete, target folders) and platform servers (selection); listing and reading tools on any type.
• references/troubleshooting-guide.md — every other uip agenthub message, with its fix.

What NOT to Do

• Do NOT guess a platform service or tool name, or assume orchestrator (Rule 9).
• Do NOT paste PascalCase CLI output into a payload as it is (Rule 3).
• Do NOT pass a display name or a GUID where a slug goes (Rule 1).
• Do NOT pass --yes before the user confirms the delete (Rule 8).
• Do NOT report a coded / command refresh as done when it returned Status: "Started" (Rule 7).
• Do NOT copy a --help example without adding the folder flag it omits.