Skip to content

Commit e2bcb86

Browse files
PopescuTudorclaude
andcommitted
feat(uipath-mcp-servers): add MCP server guardrails [PRODEV-1345]
The skill covers `uip agenthub mcp-guardrails list|get|create|update|delete --validator <validator>` and `uip agenthub guardrail-models list` (CLI 1.208): a Guardrails section, Critical Rule 12 (ask before choosing block), a guide with validators, settings, defaults, entity names, log or block and judge models, and troubleshooting rows. Two mocked smoke evals, guardrail-create and guardrail-update, and three activation prompts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent f4f16fd commit e2bcb86

39 files changed

Lines changed: 1444 additions & 6 deletions

‎skills/uipath-mcp-servers/SKILL.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: uipath-mcp-servers
3-
description: "UiPath Agent Gateway MCP servers (`uip agenthub mcp` / `uip agenthub mcp-tools`). Register, update, refresh tools, check connections, list, get, delete MCP servers: uipath (Orchestrator processes, agents, agentic processes, API workflows as tools), coded (published uipath-mcp Python server package), command (npx/uvx), remote (HTTP MCP URL, Relay), swagger (OpenAPI spec), platform (UiPath service operations, e.g. Test Manager); set users' own connections on a remote server; get the MCP URL a client connects to. For an agent that calls MCP tools→uipath-agents. For `uip mcp serve` (the uip CLI as an MCP server)→uipath-platform."
3+
description: "UiPath Agent Gateway MCP servers (`uip agenthub mcp` / `uip agenthub mcp-tools`). Register, update, refresh tools, check connections, list, get, delete MCP servers: uipath (Orchestrator processes, agents, agentic processes, API workflows as tools), coded (published uipath-mcp Python server package), command (npx/uvx), remote (HTTP MCP URL, Relay), swagger (OpenAPI spec), platform (UiPath service operations, e.g. Test Manager); set users' own connections on a remote server; add, change or remove a server's guardrails (PII detection, prompt injection, harmful content, LLM as judge); get the MCP URL a client connects to. For an agent that calls MCP tools→uipath-agents. For `uip mcp serve` (the uip CLI as an MCP server)→uipath-platform."
44
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
55
---
66

@@ -16,6 +16,7 @@ Agent Gateway is Orchestrator's hub for MCP servers and A2A agents: [about](http
1616
- Check whether a server works: its Integration Service connection and its tools ([Checking a Server](#checking-a-server)).
1717
- Get the `McpUrl` an MCP client connects to.
1818
- List, set or delete a user's own Integration Service connection on a `remote` server ([Per-User Connections](#per-user-connections)).
19+
- Add, change or remove a server's built-in guardrails: PII detection, prompt injection, harmful content, LLM as judge ([Guardrails](#guardrails)).
1920
- Find the UiPath services and tool names a `platform` server can expose.
2021

2122
**Tools — `uip agenthub mcp-tools`:**
@@ -56,16 +57,18 @@ These are the things the CLI does not advertise in `--help`.
5657

5758
11. **`not_supported` is final.** `ErrorCode: not_supported` (`<OPERATION> isn't supported on the connected environment.`) means Agent Gateway on the connected environment does not offer that feature ([Automation Suite](#automation-suite)). Another attempt, folder or flag gets the same answer. Tell the user what is missing there; do not switch to another server type or environment unless they ask.
5859

60+
12. **Ask before choosing `block`.** When the user did not say whether a guardrail stops a violating call or only logs it, ask. `block` fails closed: when the validator cannot answer, the call is blocked too. An `llm-as-judge` rule needs the caller's user token, so with `block` it blocks every call made with a PAT: say so before creating one, also when the user asked for `block`. Never default to `block`.
61+
5962
## Folder Context
6063

6164
| Command | Folder input |
6265
|---------|--------------|
6366
| `mcp list` | one of `--folder-key`, `--folder-path`, `--all-folders`, required |
64-
| `mcp get`, `mcp create <TYPE>`, `mcp update` (incl. `--print-schema`, `--dry-run`), `mcp delete`, `mcp refresh-tools`, `mcp-user-connections list` / `set` / `delete` (with `--mcp <SLUG>`) | `--folder-key` or `--folder-path`, required |
67+
| `mcp get`, `mcp create <TYPE>`, `mcp update` (incl. `--print-schema`, `--dry-run`), `mcp delete`, `mcp refresh-tools`, `mcp-user-connections list` / `set` / `delete`, `mcp-guardrails list` / `get` / `create` / `update` / `delete` (both with `--mcp <SLUG>`) | `--folder-key` or `--folder-path`, required |
6568
| 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 |
6669
| `mcp-tools candidates` | optional: tenant-wide without one |
6770
| `mcp create <TYPE> --print-schema` | none (folder flags are ignored) |
68-
| `mcp template`, `mcp-tools template`, `platform-services list`, `platform-tools list` | none: a folder flag fails as `unknown option` |
71+
| `mcp template`, `mcp-tools template`, `platform-services list`, `platform-tools list`, `guardrail-models list` | none: a folder flag fails as `unknown option` |
6972

7073
- Find folders with `uip or folders list --output json`: pass a row's `Key` as `--folder-key` or its `Path` as `--folder-path`.
7174
- Personal workspace folders (`<USER_EMAIL>'s workspace`) do NOT resolve by name: use `--folder-key`.
@@ -142,7 +145,7 @@ Agent Gateway's **Check connection** tests a server's Integration Service connec
142145

143146
- **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). `This MCP connection has no stored OAuth refresh token, …` means the connection's OAuth app issues no refresh token, and signing in again alone does not fix it: the app must issue refresh tokens (a GitHub OAuth App: tick **Expire user access tokens**; other providers: grant offline access), then the owner signs in again. Until then Integration Service may disable the connection (`… temporarily disabled due to multiple unsuccessful attempts`), and `refresh-tools` fails with `Failed to retrieve authentication token from Integration Service connection`. Tell the user; do not create, swap or clear a connection to get past it.
144147
- **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](references/troubleshooting-guide.md#refresh)). 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` ([Per-User Connections](#per-user-connections) lists them).
145-
- `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.
148+
- `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 guardrails set on those tools (the server's own [guardrails](#guardrails) stay). When the user only asked to check the server, say so before running it.
146149

147150
## Per-User Connections
148151

@@ -159,6 +162,19 @@ A `remote` server calls with its own Integration Service connection (`--connecti
159162

160163
`Status`: `Active` — the connection is Enabled. `RequiresAuth` — it expired or failed, or Integration Service no longer finds it for that user: its owner re-authenticates it (`uip is connections edit <CONNECTION_ID>`, which hands back a link to finish in a browser), or `set` another. `Inactive` — the server or the connection is disabled. `Unavailable` — Agent Gateway could not reach Integration Service: list again. Errors: [troubleshooting](references/troubleshooting-guide.md#per-user-connections).
161164

165+
## Guardrails
166+
167+
`uip agenthub mcp-guardrails` manages a server's built-in guardrails: `pii-detection`, `prompt-injection`, `harmful-content` and `llm-as-judge`. A rule screens every tool call of the server, before the tool runs and on its result. A server has at most one rule per validator, so `--validator` names the rule.
168+
169+
- `uip agenthub mcp-guardrails list --mcp <SLUG> --folder-path <FOLDER_PATH> --output json` — every rule, with its decoded `Settings`.
170+
- `uip agenthub mcp-guardrails get --validator <VALIDATOR> --mcp <SLUG> --folder-path <FOLDER_PATH> --output json`
171+
- `uip agenthub mcp-guardrails create --validator <VALIDATOR> --mcp <SLUG> --action <log|block> --folder-path <FOLDER_PATH> --output json`, plus the validator's settings. When the user did not say which `--action`, ask (Rule 12). `block` needs `--reason`, the message the caller gets, except on `prompt-injection`. `llm-as-judge` with `block` blocks every call made with a PAT: tell the user before creating it, also when they asked for `block`. Settings you leave out take the Agent Gateway defaults, the selected entities included: pass `--entity` for exactly what the user named.
172+
- `uip agenthub mcp-guardrails update --validator <VALIDATOR> --mcp <SLUG> --folder-path <FOLDER_PATH> --output json`, plus the settings to change. Everything you leave out is kept, the rule's on/off state included. `--entity` replaces the whole selection: to add an entity, pass the ones already selected too. Never delete and create a rule again to change it.
173+
- `uip agenthub mcp-guardrails delete --validator <VALIDATOR> --mcp <SLUG> --folder-path <FOLDER_PATH> --yes --output json` — confirm first (Rule 8). No flag turns a rule off: off means `delete`.
174+
- `uip agenthub guardrail-models list --output json` — the judge models an `llm-as-judge` rule can use (`--model`).
175+
176+
Writes take `--dry-run`. `create` and `update` return the stored rule, and `delete` reports `Deleted: true` with the removed `Ids` (Rule 5). Never guess an entity name or a judge model. `list` rows with `Managed: false` (tool-level rules, other guardrail types) are not the CLI's to change: leave them and tell the user. Which validator for which request, every setting with its defaults, the entity names: [references/guardrails-guide.md](references/guardrails-guide.md). Errors: [troubleshooting](references/troubleshooting-guide.md#guardrails).
177+
162178
## Tools (`uip agenthub mcp-tools`)
163179

164180
| Verb | Works on |
@@ -190,7 +206,8 @@ Flags, defaults, target folders, `update`, `delete`, `get` and paging: [referenc
190206

191207
- [references/updating-servers-guide.md](references/updating-servers-guide.md) — payload fields per type, `uipath` server updates, masked values, moving a server to another host.
192208
- [references/tools-guide.md](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.
193-
- [references/troubleshooting-guide.md](references/troubleshooting-guide.md) — every other `uip agenthub` message, with its fix, including per-user connections.
209+
- [references/guardrails-guide.md](references/guardrails-guide.md) — which validator for which request, settings and defaults, entity names, log or block, judge models, changing and removing a rule.
210+
- [references/troubleshooting-guide.md](references/troubleshooting-guide.md) — every other `uip agenthub` message, with its fix, including per-user connections and guardrails.
194211

195212
## What NOT to Do
196213

@@ -201,3 +218,6 @@ Flags, defaults, target folders, `update`, `delete`, `get` and paging: [referenc
201218
- Do NOT report a `coded` / `command` refresh as done when it returned `Status: "Started"` (Rule 7).
202219
- Do NOT copy a `--help` example without adding the folder flag it omits.
203220
- Do NOT retry a `not_supported` failure, or switch server type to get past it, without asking (Rule 11).
221+
- Do NOT choose `block` for a guardrail the user did not ask to block (Rule 12).
222+
- Do NOT guess a guardrail entity name or judge model ([Guardrails](#guardrails)).
223+
- Do NOT delete and create a guardrail again to change it: `mcp-guardrails update` keeps what you do not pass.
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# MCP Server Guardrails
2+
3+
`uip agenthub mcp-guardrails` manages a server's built-in guardrails, the rules the Agent Gateway UI configures. Every command takes `--mcp <SLUG>` and the server's folder ([Folder Context](../SKILL.md#folder-context)). A rule screens every tool call of the server, including tools added later, before the tool runs and on its result.
4+
5+
## Which Validator
6+
7+
| The user wants to catch | `--validator` |
8+
|---|---|
9+
| Personal data: emails, card numbers, addresses, ID numbers | `pii-detection` |
10+
| Input that tries to override instructions: jailbreaks, injected commands | `prompt-injection` |
11+
| Hate, self-harm, sexual or violent content | `harmful-content` |
12+
| Anything else the user can describe in words: a policy, a topic | `llm-as-judge` |
13+
14+
A server has at most one rule per validator. Two kinds of personal data go in one `pii-detection` rule with both entities.
15+
16+
## Log or Block
17+
18+
- `--action block` stops a violating call, and the caller gets `--reason`. `block` needs `--reason`, except on `prompt-injection`.
19+
- `--action log` lets the call through and records the violation at `--severity info|warning|error` (default `info`). `--reason` goes only with `block`, `--severity` only with `log`.
20+
- `block` fails closed: when the validator cannot answer, the call is blocked too.
21+
- `llm-as-judge` needs the caller's user token. A caller with a PAT always gets `Unavailable` from it, so a blocking `llm-as-judge` rule blocks every call made with a PAT. Tell the user before creating one.
22+
23+
When the user did not say which action they want, ask ([Rule 12](../SKILL.md#critical-rules)).
24+
25+
## Settings
26+
27+
| Validator | Flags | Defaults on create | Values |
28+
|---|---|---|---|
29+
| `pii-detection` | `--entity <NAME>` (repeatable, or comma-separated), `--entity-threshold <NAME>=<VALUE>` (repeatable) | `Email` 0.7, `Address` 0.5; other entities 0.7 | 0 to 1 |
30+
| `harmful-content` | `--entity <NAME>`, `--entity-threshold <NAME>=<VALUE>` | `Hate` 4, `Violence` 2; other entities 2 | 0, 2, 4 or 6 |
31+
| `prompt-injection` | `--threshold <VALUE>` | 0.5 | 0 to 1 |
32+
| `llm-as-judge` | `--instructions <TEXT>` and `--model <NAME>` (both required on create), `--positive-example <TEXT>` and `--negative-example <TEXT>` (up to 3 each), `--threshold <VALUE>` | 2 | 0, 2, 4 or 6 |
33+
34+
A create without `--entity` selects the default entities (`Email` and `Address`, or `Hate` and `Violence`): pass `--entity` for exactly what the user named. A flag another validator takes is refused, and so is an `--entity-threshold` for an entity that is not selected. Every value is checked before any call.
35+
36+
### Entities
37+
38+
Names match ignoring case. Map the user's words to these names and never invent one: "credit cards" is `CreditCardNumber`, "SSN" is `USSocialSecurityNumber`. When nothing fits, show the list and ask.
39+
40+
- `pii-detection`: `Person`, `Address`, `Date`, `PhoneNumber`, `Email`, `CreditCardNumber`, `InternationalBankingAccountNumber`, `SwiftCode`, `ABARoutingNumber`, `USDriversLicenseNumber`, `UKDriversLicenseNumber`, `USIndividualTaxpayerIdentification`, `UKUniqueTaxpayerNumber`, `USBankAccountNumber`, `USSocialSecurityNumber`, `UsukPassportNumber`, `URL`, `IPAddress`.
41+
- `harmful-content`: `Hate`, `SelfHarm`, `Sexual`, `Violence`.
42+
43+
### Judge Models
44+
45+
`--model` takes a `Name` from `uip agenthub guardrail-models list --output json`, which lists the tenant's models and needs no folder. Never guess one: a name the tenant does not offer is refused.
46+
47+
## Changing a Rule
48+
49+
- `update` applies only the flags you pass and keeps the rest: `--action log` alone keeps the threshold and the entities.
50+
- `--entity` replaces the whole selection. Entities you keep keep their thresholds; new ones get the defaults.
51+
- From `block` to `log` the reason is dropped and `--severity` applies (default `info`); from `log` to `block`, pass `--reason`.
52+
- `update` writes the new rule, then deletes the old one, so the server is never unguarded, and the new rule keeps the old one's on/off state. A second run with the same flags writes nothing.
53+
- When a delete fails, both rules apply until the old one is gone: run the same `update` again.
54+
- `get` shows `OlderDuplicates` when the server has more than one rule of the validator (written outside the CLI); `update` and `delete` remove them.
55+
56+
## Removing a Rule
57+
58+
`uip agenthub mcp-guardrails delete --validator <VALIDATOR> --mcp <SLUG> --folder-path <FOLDER_PATH> --yes --output json` removes every rule of that validator. It never prompts: confirm with the user first ([Rule 8](../SKILL.md#critical-rules)). The CLI has no flag that turns a rule off, so off means `delete`.
59+
60+
## Rules the CLI Does Not Manage
61+
62+
`list` shows every rule. Rows with `Managed: false` are tool-level rules, other guardrail types or unknown validators, with their raw `Configuration`. `get`, `update` and `delete` act only on managed rules: leave the others as they are and tell the user.

0 commit comments

Comments
 (0)