> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/mcp-servers.md).

# mcp-servers

Customer-built MCP (Model Context Protocol) server resources that expose a chosen slice of Celigo Tools and builder-mode APIs as an MCP endpoint for external AI clients (Cursor, Claude, ChatGPT, Windsurf, and anything else that speaks MCP).

What the UI calls **Capability Sets** is stored as `permissionSets[]` — an embedded array on the MCP server document, not a top-level resource. Each entry is `{_id, name, description?, accessLevel: read|write, _toolIds[], _apiIds[]}`; the server generates `_id`, which is the stable handle end-user grants reference as `pset:<_id>` (alongside `tool:<id|all>`, which also covers prompts via `prompts[]._id`, and `api:<id|all>`).

> ⚠️ **PUT erases capability sets.** The server resets `permissionSets` to `[]` on any full PUT that omits it — an `update` whose body lacks the field silently deletes every capability set and orphans every `pset:` grant that pointed at one (older documents omit the key on GET entirely, so the omission is easy to miss). Prefer `set`: `name`/`disabled` apply as an atomic PATCH, and every other field goes GET + modify + PUT with the complete document, which preserves them.

**REST API**: [MCP Servers](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers)

```
celigo mcp-servers <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                             | Purpose                                                                                                                |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `list`                                 | List every MCP server on the account.                                                                                  |
| `get <id>`                             | Fetch one MCP server by ID.                                                                                            |
| `create`                               | Create from a JSON body (`--file <path>` or stdin).                                                                    |
| `update <id>`                          | Full PUT replace from a JSON body (`--file <path>` or stdin).                                                          |
| `set <id> <key=value>...`              | Safe field edit: `name`/`disabled` via atomic PATCH, everything else GET + modify + PUT. Supports `key=file://<path>`. |
| `delete <id>`                          | Delete an MCP server.                                                                                                  |
| `dependencies <id>` (alias `used-by`)  | List resources that depend on this MCP server.                                                                         |
| `audit <id>`                           | Show the MCP server's audit log (change history).                                                                      |
| `effective-access <id>`                | Compile every end user who can reach this server, with each grant's source.                                            |
| `assign-end-users <id> <ashareIds...>` | Bulk-assign the server's capabilities to end users (replaces each listed user's grant).                                |
| `assign-groups <id> <groupIds...>`     | Bulk-assign the server's capabilities to end-user groups (replaces each listed group's grant).                         |

***

## `celigo mcp-servers list`

List every MCP server configured on the account.

**Signature**

```bash
celigo mcp-servers list [flags]
```

**Arguments**

*None.*

**Flags**

*None beyond* [*global flags*](/cli/getting-started/global-flags.md)*.*

**Example**

```bash
celigo mcp-servers list --format table
```

**Corresponds to**: [`GET /v1/mcpservers`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#get-v1-mcpservers) (operationId: `listMcpServers`).

***

## `celigo mcp-servers get`

Fetch a single MCP server by ID, including its tools, APIs, and override settings.

**Signature**

```bash
celigo mcp-servers get <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Flags**

*None beyond* [*global flags*](/cli/getting-started/global-flags.md)*.*

**Example**

```bash
celigo mcp-servers get 5f83a9b2c7d3e8f1a2b3c4d5 --format json | jq '{name,relativeURI,disabled}'
```

**Corresponds to**: [`GET /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#get-v1-mcpservers-_id) (operationId: `getMcpServerById`).

***

## `celigo mcp-servers create`

Create an MCP server from a JSON body. Read the body from a file with `-f, --file` (recommended), or pipe it on stdin. Servers are created disabled by default; at least one tool or API must be enabled before the server itself can be enabled.

**Signature**

```bash
celigo mcp-servers create --file <path>
celigo mcp-servers create < mcp-server.json     # or pipe on stdin
```

**Arguments**

*None.*

**Flags**

| Flag                | Type   | Default | Description                                                                                                  |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| `-f, --file <path>` | string | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1. |

**Request body**

A JSON object matching the `POST /v1/mcpservers` request schema, including the `tools[]`, `apis[]`, `annotations`, and override fields.

**Example**

```bash
celigo mcp-servers create --file ./mcp-server.json
```

**Corresponds to**: [`POST /v1/mcpservers`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#post-v1-mcpservers) (operationId: `createMcpServer`).

***

## `celigo mcp-servers update`

Full PUT replace of an MCP server from a JSON body (`--file <path>` or stdin). Omitted fields are erased — round-trip via `get` first, or prefer `set` for targeted edits.

> ⚠️ **`update` replaces the entire MCP server.** Any field you omit from the body is erased, including `tools[]` and `apis[]` — and a body that omits `permissionSets` **erases every capability set** (the API resets the field to `[]`), orphaning every `pset:` grant that points at one. Include the complete `permissionSets` array in the body, or prefer `set`, which round-trips the full document and preserves them.

**Signature**

```bash
celigo mcp-servers update <id> --file <path>
celigo mcp-servers update <id> < mcp-server.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Flags**

| Flag                | Type    | Default | Description                                                                                                  |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `-f, --file <path>` | string  | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1. |
| `--force`           | boolean | `false` | Submit even if the body contains masked credential values (`***`) copied from a `GET`.                       |

**Request body**

A JSON object matching the `PUT /v1/mcpservers/{_id}` request schema.

**Example**

```bash
celigo mcp-servers get 5f83a9b2c7d3e8f1a2b3c4d5 --format json \
  | jq '.disabled = false' \
  | celigo mcp-servers update 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PUT /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#put-v1-mcpservers-_id) (operationId: `updateMcpServer`).

***

## `celigo mcp-servers set`

Safe field edit. Whitelisted fields (`name`, `disabled`) are applied via an atomic `PATCH`; every other field goes GET + in-memory mutation + PUT with the complete document — which preserves `permissionSets`, unlike a hand-written `update` body. Dot notation and array indexing are supported. A `null` RHS removes the field (or splices an array element). A `key=file://<path>` value loads that field's value from a file instead of the command line (a leading `~` and relative paths are supported).

**Signature**

```bash
celigo mcp-servers set <id> <key=value>...
```

**Arguments**

| Argument         | Type              | Required | Description                                                                 |
| ---------------- | ----------------- | -------- | --------------------------------------------------------------------------- |
| `<id>`           | string            | Yes      | MCP server ID.                                                              |
| `<key=value>...` | string (variadic) | Yes      | One or more assignments, e.g. `disabled=false` or `tools[0].disabled=true`. |

**Flags**

*None beyond* [*global flags*](/cli/getting-started/global-flags.md)*.*

**Example**

```bash
# Append a tool reference to the server
celigo mcp-servers set 5f83a9b2c7d3e8f1a2b3c4d5 \
  'tools[2]={"_toolId":"6a1b2c3d4e5f6a7b8c9d0e1f"}'

# Enable the server and rename it
celigo mcp-servers set 5f83a9b2c7d3e8f1a2b3c4d5 disabled=false 'name=Sales copilot (prod)'
```

**Corresponds to**: [`GET /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#get-v1-mcpservers-_id) + [`PUT /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#put-v1-mcpservers-_id) (operationIds: `getMcpServerById`, `updateMcpServer`).

***

## `celigo mcp-servers delete`

Delete an MCP server by ID.

> ⚠️ **Deleting an MCP server cannot be undone.** External AI clients that connect through this server's endpoint immediately lose access.

**Signature**

```bash
celigo mcp-servers delete <id> [--yes]
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Flags**

| Flag          | Type | Default | Description                               |
| ------------- | ---- | ------- | ----------------------------------------- |
| `-y`, `--yes` | bool | `false` | Skip the interactive confirmation prompt. |

**Example**

```bash
celigo mcp-servers delete 5f83a9b2c7d3e8f1a2b3c4d5 --yes
```

**Corresponds to**: [`DELETE /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers#delete-v1-mcpservers-_id) (operationId: `deleteMcpServer`).

***

## `celigo mcp-servers dependencies`

List resources that depend on this MCP server (alias: `used-by`). Use it to check whether a server is safe to delete — an empty result means nothing references it.

**Signature**

```bash
celigo mcp-servers dependencies <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Flags**

*None beyond* [*global flags*](/cli/getting-started/global-flags.md)*.*

**Example**

```bash
celigo mcp-servers dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/mcpservers/{_id}/dependencies`.

***

## `celigo mcp-servers audit`

Show the audit log (change history) for one MCP server.

**Signature**

```bash
celigo mcp-servers audit <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Flags**

*None beyond* [*global flags*](/cli/getting-started/global-flags.md)*.*

**Example**

```bash
celigo mcp-servers audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/mcpservers/{_id}/audit`.

***

## `celigo mcp-servers effective-access <id>`

Compile who can reach this MCP server: every end user with access, their effective tools, and the source of each grant (`direct`, `group:<name>`, `pset:<name>`, `role:<name>`). The per-user mirror is [`end-users effective-access`](/cli/commands/end-users.md#celigo-end-users-effective-access-ashareid), which compiles the same picture for one person across every server.

**Signature**

```bash
celigo mcp-servers effective-access <id>
```

**Arguments**

| Argument | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `<id>`   | string | Yes      | MCP server ID. |

**Example**

```bash
celigo mcp-servers effective-access 6a1b2c3d4e5f6a7b8c9d0e1f --format json
```

**Corresponds to**: [`GET /v1/mcpservers/{_id}/effective-access`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers)

***

## `celigo mcp-servers assign-end-users <id> <ashareIds...>`

Bulk-assign this server's capabilities to end users — up to 100 per call. Requires `full` mode.

The assignment **replaces, not appends**: each listed end user's grant for *this* server becomes exactly the given `--capabilities` — whatever they previously had on this server is dropped. Grants for other servers, wildcard all-server grants, and end users not listed are untouched. A mid-batch failure stops the batch: the response lists the end users already updated plus the error.

**Signature**

```bash
celigo mcp-servers assign-end-users <id> <ashareIds...> --capabilities <cap,...>
```

**Arguments**

| Argument         | Type              | Required | Description                                                                                                       |
| ---------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `<id>`           | string            | Yes      | MCP server ID.                                                                                                    |
| `<ashareIds...>` | string (variadic) | Yes      | End-user access-record ids from [`end-users list`](/cli/commands/end-users.md#celigo-end-users-list) (up to 100). |

**Flags**

| Flag                    | Type   | Default | Description                                                                                                                                                                                         |
| ----------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--capabilities <caps>` | string | —       | **Required.** Capabilities to grant on this server, comma-separated: `tool:all`, `tool:<id>`, `api:all`, `api:<id>`, or `pset:<permissionSetId>` (a capability set's `_id` from `mcp-servers get`). |

**Example**

```bash
celigo mcp-servers assign-end-users 6a1b2c3d4e5f6a7b8c9d0e1f 68f0a9b2c7d3e8f1a2b3c4d5 \
  --capabilities tool:all,pset:6c2d3e4f5a6b7c8d9e0f1a2b
```

**Corresponds to**: [`PUT /v1/mcpservers/{_id}/endusers`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers)

***

## `celigo mcp-servers assign-groups <id> <groupIds...>`

Bulk-assign this server's capabilities to end-user groups — up to 100 per call. Requires `full` mode.

Same replace semantics as `assign-end-users`: each listed group's grant for *this* server becomes exactly the given `--capabilities`; grants for other servers, wildcard grants, and groups not listed are untouched. Member end users receive the change through membership. A mid-batch failure stops the batch and reports the groups already updated.

**Signature**

```bash
celigo mcp-servers assign-groups <id> <groupIds...> --capabilities <cap,...>
```

**Arguments**

| Argument        | Type              | Required | Description                                                                             |
| --------------- | ----------------- | -------- | --------------------------------------------------------------------------------------- |
| `<id>`          | string            | Yes      | MCP server ID.                                                                          |
| `<groupIds...>` | string (variadic) | Yes      | Group ids from [`groups list`](/cli/commands/groups.md#celigo-groups-list) (up to 100). |

**Flags**

| Flag                    | Type   | Default | Description                                                                                                                                       |
| ----------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--capabilities <caps>` | string | —       | **Required.** Capabilities to grant on this server, comma-separated: `tool:all`, `tool:<id>`, `api:all`, `api:<id>`, or `pset:<permissionSetId>`. |

**Example**

```bash
celigo mcp-servers assign-groups 6a1b2c3d4e5f6a7b8c9d0e1f 68a1b2c3d4e5f6a7b8c9d0e1 \
  --capabilities pset:6c2d3e4f5a6b7c8d9e0f1a2b
```

**Corresponds to**: [`PUT /v1/mcpservers/{_id}/groups`](https://developer.celigo.com/api/api-reference/ai-and-mcp/mcp-servers)

***

## Gotchas

* **This resource is not the Celigo Platform MCP.** The `mcp-servers` command manages builder-side MCP endpoints *you* create to expose a chosen slice of your Tools and builder-mode APIs. For the first-party hosted MCP server that AI agents use to manage your whole account, see the [MCP docs](https://developer.celigo.com/mcp).
* **Editing tools, APIs, or credentials is a body edit, not a dedicated subcommand.** There is no `tools add`, `tools remove`, `apis add`, or `tokens rotate` — mutate `tools[]` / `apis[]` via `set` (for append/patch) or `update` (for full replace).
* **`update` is a full PUT replace.** Omitted fields are erased. Always round-trip via `get` + `jq` first, or reach for `set`.
* **A PUT that omits `permissionSets` erases every capability set.** The API resets the field to `[]` rather than preserving it, and older documents omit the key on GET entirely, so the omission is easy to miss. Every `pset:` grant pointing at an erased set is orphaned. `set` is the safe editor.
* **The `assign-*` commands replace, not append.** Each listed end user's or group's grant for the server becomes exactly the given `--capabilities`. To add a capability, read the current grant from `effective-access` first and pass the complete list.
* **Servers start disabled, and need at least one enabled child.** A freshly created server's `disabled` cannot be flipped to `false` until one of its `tools[]` or `apis[]` entries is enabled.
* **`relativeURI` is unique per account** and must match `/<segment>` (alphanumerics, underscores, hyphens). A collision is rejected with `422 Unprocessable Entity`.
* **No CLI surface for `/preview` or `/logs`.** Those endpoints exist at `/api/mcpservers/{id}/preview` and `/api/mcpservers/{id}/logs` but are session-auth only and not reachable via bearer token — use the UI for preview and log inspection.

## Related

* [tools](/cli/commands/tools.md) — the primary building block MCP servers expose; create tools first, then reference them from `tools[]`.
* [apis](/cli/commands/apis.md) — builder-mode APIs can also be exposed through an MCP server via `apis[]`.
* [end-users](/cli/commands/end-users.md) — the external people granted access; `effective-access` here mirrors their per-user view.
* [groups](/cli/commands/groups.md) / [roles](/cli/commands/roles.md) — bundle grants that reference this server's tools, APIs, and capability sets.