> 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/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/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/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/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/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/mcp-servers#get-v1-mcpservers-_id) + [`PUT /v1/mcpservers/{_id}`](https://developer.celigo.com/api/api-reference/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/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/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/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/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/mcp-servers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.