# uip agenthub

> Syntax and options for `uip agenthub mcp`, which registers and manages AgentHub MCP servers — the tools coded and low-code agents can call.

`uip agenthub` manages **UiPath AgentHub**: MCP (Model Context Protocol) server registrations and their tools, plus remote A2A (agent-to-agent) agent registrations. An AgentHub MCP server is a named, folder-scoped resource that exposes a set of callable tools to coded and low-code agents — not to be confused with the MCP wire protocol itself, which is how a client actually invokes those tools at runtime.

This resource spans two pages:

- **This page** — concepts, and `mcp` (register, list, update, delete MCP servers).
- [`mcp-tools` and `remote-a2a-agent`](./uip-agenthub-tools-a2a.md) — manage the tools attached to an MCP server, and remote A2A agent registrations.

## Concepts

- **Server type is fixed at creation and immutable afterward.** Eight named types exist in the type enum (`uipath`, `command`, `coded`, `selfhosted`, `remote`, `process-assistant`, `platform`, `swagger`), each mapped to a numeric wire value (0–7 respectively). **Only six of the eight have a working `mcp create <type>` leaf: `uipath`, `coded`, `command`, `remote`, `platform`, `swagger`.** `selfhosted` and `process-assistant` appear in the type enum, in `mcp template`'s accepted types, and even have worked examples in this command's own help text — but there is no `mcp create selfhosted` or `mcp create process-assistant` subcommand registered anywhere in source. Attempting either fails as an unknown command. `mcp update <slug>` dispatches by the server's *existing* type (fetched from the API), so it has no such gap — but it can only update a server that was created some other way for those two types.
- **Folder context.** AgentHub resources are Orchestrator-folder-scoped. Pass `--folder-key <guid>` or `--folder-path <path>` on every verb; `mcp list` additionally accepts `--all-folders` to enumerate every folder the caller can see (folder-by-folder, de-duplicated by slug+folder, with per-folder failures — most commonly "no AgentHub permission in that folder" — swallowed and surfaced as warnings rather than aborting the whole list). `mcp create` and `mcp delete` hard-fail before any network call if no folder is resolvable; `mcp list`/`mcp get` do not enforce this client-side even though `mcp list`'s own description says a folder context is required — omitting both there likely still fails server-side.
- **Input modes on create/update: exactly one of `--file`, `--body`, or scalar flags.** Passing more than one source is a client-side `ConflictingInput` error; passing none is `MissingInput`. `--print-schema` short-circuits either verb to print the type's expected JSON shape instead of writing anything — a fast way to see what `--file`/`--body` needs before authoring it by hand. `--dry-run` short-circuits to print the resolved mutation plan (HTTP verb, target, resolved payload) without calling the API.
- **`update` merges onto the existing server by scalar default; `--file`/`--body` fully replaces.** In scalar mode, only the flags you pass change — the rest of the fetched server's fields are preserved, including a `platform` server's existing `selectedToolNames` when `--tool` is omitted. The `type` field itself is immutable: including it in a `--file`/`--body` payload is a client-side error, not a silent no-op.

## Synopsis

```text
uip agenthub mcp list [--type <type>] [--status <s>] [--name <substr>] [--limit <n>] [--offset <n>] [--folder-key <key> | --folder-path <path> | --all-folders]
uip agenthub mcp get <slug> [--folder-key <key> | --folder-path <path>]
uip agenthub mcp create <uipath|coded|command|remote|platform|swagger> [type-specific options] [--file <path> | --body <json> | scalars] [--print-schema] [--dry-run]
uip agenthub mcp update <slug> [type-specific options] [--file <path> | --body <json> | scalars] [--print-schema] [--dry-run]
uip agenthub mcp template <type>
uip agenthub mcp delete <slug> -y [--dry-run]
uip agenthub mcp refresh-tools <slug> --folder-key <key> [--dry-run]
```

## uip agenthub mcp list

List MCP server registrations. Filters (`--type`, `--status`, `--name`) and paging (`--limit`/`--offset`) are applied client-side, since the underlying API returns a flat array.

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--type <kind>` | `uipath`\|`command`\|`coded`\|`selfhosted`\|`remote`\|`process-assistant`\|`platform`\|`swagger` | — | Filter by server type. Invalid values fail client-side before any API call. |
| `--status <s>` | string | — | Filter by status. Matched against the numeric status enum as a raw string. |
| `--name <substr>` | string | — | Case-insensitive substring match on server name. |
| `--limit <number>` | integer | 50 | Page size. |
| `--offset <number>` | integer | 0 | Row offset. |
| `--folder-key <key>` | GUID | — | Orchestrator folder. Mutually exclusive with `--all-folders`. |
| `--folder-path <path>` | string | — | Folder display name or fully-qualified path, resolved to a key via the Orchestrator SDK. |
| `--all-folders` | flag | off | Enumerate every folder the caller can see. Mutually exclusive with `--folder-key`/`--folder-path`. |
| `--login-validity <minutes>` | integer | — | Override the interactive-login token lifetime for this call. |

### Example

```bash
uip agenthub mcp list --folder-path Shared --type uipath --name invoice
```

### Data shape (--output json)

```json
{
  "Code": "AgentHubMcpList",
  "Data": {
    "items": [{ "slug": "invoice-mcp", "name": "Invoice MCP", "type": 0, "status": 0 }],
    "total": 1,
    "count": 1
  }
}
```

## uip agenthub mcp get

Get one MCP server by canonical slug. No name-lookup fallback — pass the exact slug from `mcp list`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<slug>` | yes | Canonical MCP server slug. |

### Options

| Long | Value | Description |
|---|---|---|
| `--folder-key <key>` / `--folder-path <path>` | GUID / string | Folder context. |
| `--login-validity <minutes>` | integer | Token lifetime override. |

### Example

```bash
uip agenthub mcp get invoice-mcp
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpGet", "Data": { "slug": "invoice-mcp", "name": "Invoice MCP", "type": 0 } }
```

## uip agenthub mcp create

Create an MCP server. One subcommand per type — `uipath`, `coded`, `command`, `remote`, `platform`, `swagger` (see [Concepts](#concepts) for the two type names that exist in the enum but have no working `create` leaf). All six share `--name`, `--slug` (defaults to a slugified `--name`), `--description`, `--version`, plus `--file`/`--body`/`--print-schema`/`--dry-run` and folder options. Requires a resolvable folder — fails before any network call otherwise.

### Type-specific options

| Type | Extra options | Notes |
|---|---|---|
| `uipath` | none | Payload: `{ server: {name, slug, description, version}, tools: [] }`. Tools are added afterward via `mcp-tools`. |
| `coded` | `--process-key <key>` | Backed by an Orchestrator process. `--folder-key` doubles as the payload's `folderKey`. |
| `command` | `--command <cmd>`, `--arg <arg>` (repeatable), `--env <key=value>` (repeatable) | Launches a local binary. `arguments` is the joined `--arg` list (space-separated); `environmentVariables` is a JSON-stringified object built from `--env` pairs. |
| `remote` | `--uri <uri>`, `--header <key=value>` (repeatable), `--use-relay` | `headers` is a JSON-stringified object from `--header` pairs. |
| `platform` | `--service <name>`, `--tool <name>` (repeatable) | Payload nests scalars under `server`, with `selectedToolNames` alongside it. |
| `swagger` | `--spec-url <url>`, `--use-relay`, `--filter <expr>` (repeatable, reserved) | Creates through a separate Swagger-specific API endpoint. |

### Examples

```bash
uip agenthub mcp create uipath --name InvoiceMcp --slug invoice-mcp
uip agenthub mcp create command --name LocalMcp --slug local-mcp --command npx --arg @some/server
uip agenthub mcp create remote --name RemoteMcp --slug remote-mcp --uri https://example/mcp
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpCreate", "Data": { "slug": "invoice-mcp", "name": "InvoiceMcp" } }
```

`--print-schema` returns `Code: "AgentHubMcpTemplate"` with the type's JSON Schema instead of creating anything. `--dry-run` returns `Code: "DryRun"` with the resolved mutation plan.

## uip agenthub mcp update

Update an MCP server. Dispatches by the server's *existing* type (fetched first) — the same type-specific options as `create` are all registered on `update` regardless of the target's real type, but only the ones relevant to the fetched type are merged in.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<slug>` | yes | Canonical MCP server slug. |

### Options

Same type-specific flags as `create` (`--name`, `--description`, `--version`, `--process-key`, `--command`, `--arg`, `--env`, `--uri`, `--header`, `--use-relay`, `--service`, `--tool`, `--spec-url`), plus `--file`/`--body`/`--print-schema`/`--dry-run` and folder options. `type` is immutable — including it in a `--file`/`--body` payload is a client-side error.

### Example

```bash
uip agenthub mcp update invoice-mcp --name InvoiceMcp
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpUpdate", "Data": { "slug": "invoice-mcp", "name": "InvoiceMcp" } }
```

## uip agenthub mcp template

Emit a ready-to-edit JSON skeleton for one server type — a static, connector-independent reference command (no folder options at all).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<type>` | yes | One of `uipath`, `coded`, `command`, `selfhosted`, `remote`, `process-assistant`, `platform`, `swagger` (all 8, including the two with no working `create` leaf). `swagger-mcp` is also accepted, normalized to `swagger`. |

### Example

```bash
uip agenthub mcp template uipath
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpTemplate", "Data": { "server": { "name": "uipath-mcp", "description": "", "version": "1.0.0", "isActive": true }, "tools": [] } }
```

## uip agenthub mcp delete

Delete an MCP server by slug. Destructive — requires `-y`/`--yes`. Requires a resolvable folder.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<slug>` | yes | Canonical MCP server slug. |

### Options

| Long | Description |
|---|---|
| `-y, --yes` | Required to confirm. The CLI never prompts. |
| `--dry-run` | Print the mutation plan without deleting. |

### Example

```bash
uip agenthub mcp delete invoice-mcp -y
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpDelete", "Data": { "slug": "invoice-mcp", "deleted": true } }
```

## uip agenthub mcp refresh-tools

Re-derive a server's tools from its live source (a process's schema, a remote/swagger endpoint, etc.).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<slug>` | yes | Canonical MCP server slug. |

### Options

| Long | Description |
|---|---|
| `--folder-key <key>` / `--folder-path <path>` | **One is required** — the refresh endpoint is folder-scoped (`/mcp/{folderKey}/{slug}/refresh-tools`). Missing both fails with an explicit error before any lookup. |
| `--dry-run` | Print the mutation plan without refreshing. |

Behavior differs by server type: `coded`/`command` refreshes return an async `runtimeId` (HTTP 202, `status: "Started"`); `remote`/`swagger`/`platform` refresh synchronously (`status: "Refreshed"`, `toolCount`); `uipath` and `selfhosted` servers are rejected locally — their tools are manually authored, not derived — with a `NextCommand` hint pointing at [`mcp-tools create-resource`](./uip-agenthub-tools-a2a.md#uip-agenthub-mcp-tools-create-resource-create-raw).

### Example

```bash
uip agenthub mcp refresh-tools remote-mcp --folder-key f1f2f3f4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{ "Code": "AgentHubMcpRefreshTools", "Data": { "status": "Refreshed", "toolCount": 3 } }
```

Async (202) responses instead return `{ "runtimeId": "...", "status": "Started" }`.

## Related

- [`mcp-tools` and `remote-a2a-agent`](./uip-agenthub-tools-a2a.md) — manage tools on a server, and remote A2A agent registrations.

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)