# uip mcp

> `uip mcp` exposes the CLI as a [Model Context Protocol](https://modelcontextprotocol.io/) server, letting MCP-aware clients (Claude Desktop, Cursor, VS Code MCP hosts, etc.) invoke any `uip` subcommand as a tool.

`uip mcp` exposes the CLI as a [Model Context Protocol](https://modelcontextprotocol.io/) server, letting MCP-aware clients (Claude Desktop, Cursor, VS Code MCP hosts, etc.) invoke any `uip` subcommand as a tool.

:::note
Skills are the primary path for teaching AI coding agents to use the UiPath CLI — see [`uip skills`](./uip-skills.md) and [Skills](./concepts-skills.md). MCP is provided as an alternative for clients that do not support skills or that prefer MCP-style tool invocation. If your agent supports skills, prefer skills.
:::

## Synopsis

```
uip mcp serve
```

`uip mcp serve` honors the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`) for the server process itself; the tool it exposes to clients accepts any CLI command string and returns its combined stdout/stderr. Exit codes follow the [standard contract](./exit-codes.md).

## uip mcp serve

Starts the MCP server on **stdio** (newline-delimited JSON-RPC). There is no network listener, no HTTP transport, and no port configuration — stdio is the only supported transport in 1.x.

### Arguments

None.

### Options

None. The server runs until the stdio transport is closed by the client (usually when the host application quits).

### Behavior

- The server advertises a single tool, `run_command`, which takes one argument:
  - `command` *(string)* — The CLI command to run, without the `uip` prefix. Example: `"login status --output json"`.
- The server enumerates every installed `uip` subcommand at startup and includes a rendered command catalog in the MCP tool's description. `mcp` and `help` subcommands are excluded from that catalog — the client cannot ask the server to start another MCP server.
- On each `run_command` call, the CLI runs the requested command in a child invocation and returns the combined stdout/stderr. If the child exits non-zero, or if it wrote an error envelope to stderr with a zero exit code (a rare case where a command reports failure without changing the exit code), the result is flagged `isError: true` and prefixed with `Error (exit code N):`.

**Example** (starting the server from a shell — normally your MCP client launches this for you):

```bash
uip mcp serve
```

## Configuring an MCP client

All configurations use the same command/args. The server name (`uipath` below) is arbitrary.

**Claude Desktop** — edit `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "uipath": {
      "command": "uip",
      "args": ["mcp", "serve"]
    }
  }
}
```

Restart Claude Desktop after saving.

**Claude Code** — add via its CLI:

```bash
claude mcp add uipath -- uip mcp serve
```

**Cursor** — edit `.cursor/mcp.json` (project-local) or the Cursor global MCP config:

```json
{
  "mcpServers": {
    "uipath": {
      "command": "uip",
      "args": ["mcp", "serve"]
    }
  }
}
```

**VS Code** — edit `.vscode/mcp.json`:

```json
{
  "servers": {
    "uipath": {
      "command": "uip",
      "args": ["mcp", "serve"]
    }
  }
}
```

## Lifecycle

The MCP server has no standalone stop command. It lives as a child process of the MCP client and exits when:

- the client closes the stdio connection,
- the host application quits, or
- you remove the server entry from the client's config and reload.

## Authentication and tenant context

`uip mcp serve` does not manage credentials. Every `run_command` invocation reads the same stored session as an interactive shell would — so you must have run [`uip login`](./uip-login.md) separately before asking the agent to call commands that require auth. If no session exists, the tool result will contain the usual `AuthenticationError` payload (see [Exit codes](./exit-codes.md)).

## Data shape

Tool results follow the MCP tool-call contract. On success:

```json
{
  "content": [
    { "type": "text", "text": "<combined stdout/stderr>" }
  ],
  "isError": false
}
```

On failure, `isError` is `true` and `text` is prefixed with `Error (exit code N):`. The inner text is the normal CLI output (JSON if the caller requested `--output json`, otherwise the default format).

## Considerations

- **Always request JSON from inside MCP calls.** Pass `--output json` in the `command` string so the agent receives structured data instead of tables.
- **No filtering of destructive commands.** The `run_command` tool can invoke any `uip` subcommand, including `logout`, `tools uninstall`, and tools that mutate Orchestrator state. Treat the MCP server as an authenticated shell and scope the agent accordingly.
- **`help` and `mcp` are hidden from the catalog** but can still be invoked by the client. Nothing prevents `mcp serve` from being called recursively through another `run_command`; this is a no-op in practice because the outer server controls stdio.

## Related

- [`uip skills`](./uip-skills.md) — primary AI integration path.
- [Skills](./concepts-skills.md) — why skills are preferred over raw MCP access for agent ergonomics.
- [Authentication](./authentication.md) — the session `run_command` inherits.
- [Global options](./global-options.md) — `--output json` inside MCP calls.