@celigo/api-specs 0.2.1

package/dist/mcp-server.yml

@@ -0,0 +1,2656 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: MCP Servers
+  description: API for managing Celigo MCP servers — endpoints that expose integration tools and APIs to AI agents and MCP clients.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing MCP (Model Context Protocol) servers in Celigo.
+      MCP servers expose integration tools, builder-mode APIs,
+      and inline prompt templates as MCP-compatible endpoints that can be consumed by
+      AI agents and other MCP clients.
+    - |-
+      Each MCP server:
+      - Has a unique `relativeURI` that forms part of its endpoint path
+      - Contains a collection of **tools** (referencing Tool resources), **APIs** (referencing builder-mode API resources), **prompts** (inline reusable templates), and **resources** (Celigo Storage files served to clients)
+      - Can be enabled or disabled at both the server level and individual tool/API level
+      - Supports MCP annotations on tools for hinting behavior (read-only, idempotent, destructive, etc.)
+      - Supports tool overrides for customizing connections, exports, imports, and routing per-server
+      - Exposes prompts via `prompts/list` and `prompts/get` with Handlebars-style argument substitution
+      - Carries **permission sets** ("Capability Sets" in the UI) — named bundles of its tools and APIs granted to end users via `pset:<_id>` capability strings on end-user, group, and role resource grants
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: MCP Servers
+    description: |-
+      MCP servers expose integration tools and builder-mode APIs as
+      MCP-compatible endpoints consumed by AI agents and MCP clients.
+
+      Each server has a unique `relativeURI`, a collection of tools and APIs
+      (each individually enable/disable), optional prompt templates, optional
+      file resources from Celigo Storage, and optional OAuth configuration.
+      Tools support MCP annotations (read-only, idempotent, destructive,
+      open-world) and per-server overrides for connections, exports, imports,
+      and routing. Permission sets ("Capability Sets" in the UI) bundle a
+      server's tools and APIs into named grants for end users, and the
+      server-scoped access endpoints bulk-assign capabilities to end users
+      and groups and report compiled effective access.
+
+      ## MCP server schema
+
+      {% openapi-schemas spec="mcp-server" schemas="MCPServer" grouped="true" %}
+paths:
+  /v1/mcpservers:
+    get:
+      x-internal: false
+      summary: List MCP servers
+      description: Returns all MCP servers in the account.
+      x-celigo-ai-guidance:
+        - |-
+          Returns a list of all MCP servers configured in the account.
+          If no MCP servers exist in the account,
+          a 204 response with no body will be returned.
+      operationId: listMcpServers
+      tags:
+        - MCP Servers
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: MCP server list.
+          x-celigo-ai-guidance:
+            - Successfully retrieved list of MCP servers
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Contains `<...>; rel="next"` when
+                more pages remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/MCPServer'
+              examples:
+                default:
+                  value:
+                    - _id: 69eb9fb5b4fc023618e490b8
+                      _userId: 624cb0346309dc3a543733a2
+                      name: Customer Integration MCP
+                      relativeURI: /customers
+                      description: Exposes customer management tools for AI agent consumption
+                      disabled: false
+                      tools:
+                        - _toolId: 69d462d5b9c28ea0b7f82522
+                          name: get_customer
+                          disabled: false
+                          annotations:
+                            readOnlyHint: true
+                      apis:
+                        - name: order_lookup
+                          _apiId: 68ae4264b5f755d2dd3796b4
+                          disabled: false
+                      resources: []
+                      prompts: []
+                      permissionSets:
+                        - _id: 6a7b8c9d0e1f2a3b4c5d6e7f
+                          name: Finance read-only
+                          description: Read-only invoice lookups for the finance team
+                          accessLevel: read
+                          _toolIds:
+                            - 69d462d5b9c28ea0b7f82522
+                          _apiIds: []
+                      oauth:
+                        useCeligoOauth: true
+                      createdAt: '2026-04-24T16:52:05.607Z'
+                      lastModified: '2026-05-07T15:22:16.985Z'
+        '204':
+          description: No MCP servers exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create an MCP server
+      description: |-
+        Creates an MCP server. The server is created disabled by default.
+        `name` and `relativeURI` are the only required fields;
+        `relativeURI` must be unique per account.
+      x-celigo-ai-guidance:
+        - |-
+          Creates a new MCP server that exposes tools, APIs,
+          and inline prompts as MCP-compatible endpoints.
+        - |-
+          Set the server's `relativeURI` to a value that is unique per account and follows
+          the pattern `/<segment>`,
+          where the segment contains only alphanumeric characters, underscores,
+          and hyphens.
+        - |-
+          The server is created in a disabled state by default; to enable it,
+          at least one tool, API, resource, or prompt within the server must
+          also be enabled.
+      operationId: createMcpServer
+      tags:
+        - MCP Servers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal create
+                value:
+                  name: Customer Integration MCP
+                  relativeURI: /customers
+              with_tool:
+                summary: With a tool and Celigo OAuth
+                value:
+                  name: Customer Integration MCP
+                  relativeURI: /customers
+                  description: Exposes customer management tools
+                  disabled: false
+                  tools:
+                    - _toolId: 69d462d5b9c28ea0b7f82522
+                      name: get_customer
+                      disabled: false
+                      annotations:
+                        readOnlyHint: true
+                  oauth:
+                    useCeligoOauth: true
+      responses:
+        '201':
+          description: Created MCP server.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServer'
+              examples:
+                created:
+                  summary: Created from the minimal request (disabled by default, empty arrays)
+                  value:
+                    _id: 69eb9fb5b4fc023618e490b8
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Customer Integration MCP
+                    relativeURI: /customers
+                    description: ''
+                    disabled: true
+                    tools: []
+                    apis: []
+                    resources: []
+                    prompts: []
+                    permissionSets: []
+                    createdAt: '2026-04-24T16:52:05.607Z'
+                    lastModified: '2026-04-24T16:52:05.607Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/mcpservers/{_id}:
+    get:
+      x-internal: false
+      summary: Get an MCP server
+      description: Returns the full configuration of an MCP server including tools, APIs, prompts, resources, and OAuth settings.
+      operationId: getMcpServerById
+      tags:
+        - MCP Servers
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      responses:
+        '200':
+          description: MCP server configuration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServer'
+              examples:
+                default:
+                  summary: Server exposing a tool and an API via Celigo OAuth
+                  value:
+                    _id: 69eb9fb5b4fc023618e490b8
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Customer Integration MCP
+                    relativeURI: /customers
+                    description: Exposes customer management tools for AI agent consumption
+                    disabled: false
+                    tools:
+                      - _toolId: 69d462d5b9c28ea0b7f82522
+                        name: get_customer
+                        disabled: false
+                        annotations:
+                          readOnlyHint: true
+                    apis:
+                      - name: order_lookup
+                        _apiId: 68ae4264b5f755d2dd3796b4
+                        disabled: false
+                    resources: []
+                    prompts: []
+                    permissionSets:
+                      - _id: 6a7b8c9d0e1f2a3b4c5d6e7f
+                        name: Finance read-only
+                        description: Read-only invoice lookups for the finance team
+                        accessLevel: read
+                        _toolIds:
+                          - 69d462d5b9c28ea0b7f82522
+                        _apiIds: []
+                    oauth:
+                      useCeligoOauth: true
+                    createdAt: '2026-04-24T16:52:05.607Z'
+                    lastModified: '2026-05-07T15:22:16.985Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an MCP server
+      description: |-
+        Full replacement of an MCP server's configuration. Omitted arrays
+        (`tools`, `apis`, `prompts`, `resources`, `permissionSets`) are cleared,
+        so include the complete arrays — clearing `permissionSets` this way also
+        rewrites the `pset:` grants that referenced the erased sets. `relativeURI`
+        can be changed but must remain unique per account.
+      operationId: updateMcpServer
+      tags:
+        - MCP Servers
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              full_replace:
+                summary: Full replacement — include complete arrays (omitted arrays are cleared)
+                value:
+                  name: Customer Integration MCP
+                  relativeURI: /customers
+                  description: Exposes customer management tools for AI agent consumption
+                  disabled: false
+                  tools:
+                    - _toolId: 69d462d5b9c28ea0b7f82522
+                      name: get_customer
+                      disabled: false
+                      annotations:
+                        readOnlyHint: true
+                  apis:
+                    - name: order_lookup
+                      _apiId: 68ae4264b5f755d2dd3796b4
+                      disabled: false
+                  resources:
+                    - title: Return Policy
+                      _fileId: 6a55886da387d16e4e475aa2
+                      disabled: false
+                  permissionSets:
+                    - _id: 6a7b8c9d0e1f2a3b4c5d6e7f
+                      name: Finance read-only
+                      description: Read-only invoice lookups for the finance team
+                      accessLevel: read
+                      _toolIds:
+                        - 69d462d5b9c28ea0b7f82522
+                      _apiIds: []
+                  oauth:
+                    useCeligoOauth: true
+      responses:
+        '200':
+          description: Updated MCP server.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServer'
+              examples:
+                updated:
+                  summary: Server with replaced configuration
+                  value:
+                    _id: 69eb9fb5b4fc023618e490b8
+                    _userId: 624cb0346309dc3a543733a2
+                    name: Customer Integration MCP
+                    relativeURI: /customers
+                    description: Exposes customer management tools for AI agent consumption
+                    disabled: false
+                    tools:
+                      - _toolId: 69d462d5b9c28ea0b7f82522
+                        name: get_customer
+                        disabled: false
+                        annotations:
+                          readOnlyHint: true
+                    apis:
+                      - name: order_lookup
+                        _apiId: 68ae4264b5f755d2dd3796b4
+                        disabled: false
+                    resources:
+                      - title: Return Policy
+                        _fileId: 6a55886da387d16e4e475aa2
+                        disabled: false
+                    prompts: []
+                    permissionSets:
+                      - _id: 6a7b8c9d0e1f2a3b4c5d6e7f
+                        name: Finance read-only
+                        description: Read-only invoice lookups for the finance team
+                        accessLevel: read
+                        _toolIds:
+                          - 69d462d5b9c28ea0b7f82522
+                        _apiIds: []
+                    oauth:
+                      useCeligoOauth: true
+                    createdAt: '2026-04-24T16:52:05.607Z'
+                    lastModified: '2026-05-07T15:22:16.985Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+      x-celigo-ai-guidance:
+        - |-
+          Updates an existing MCP server with the provided configuration.
+          This replaces the full server configuration including tools and APIs.
+    patch:
+      x-internal: false
+      summary: Patch an MCP server
+      description: |-
+        Partially updates an MCP server using a JSON Patch document (RFC 6902).
+        Only `/name` and `/disabled` are whitelisted paths — all other paths
+        are rejected with `not a whitelisted property`.
+      operationId: patchMcpServer
+      tags:
+        - MCP Servers
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              disable_server:
+                summary: Disable an MCP server
+                value:
+                  - op: replace
+                    path: /disabled
+                    value: true
+              rename:
+                summary: Rename an MCP server
+                value:
+                  - op: replace
+                    path: /name
+                    value: Updated Server Name
+      responses:
+        '204':
+          description: Patch applied.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete an MCP server
+      description: |-
+        Soft-deletes an MCP server. Retained in the recycle bin for 30 days
+        before permanent removal.
+      operationId: deleteMcpServer
+      tags:
+        - MCP Servers
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      responses:
+        '204':
+          description: Deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/mcpservers/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listMcpServerDependencies
+      tags:
+        - MCP Servers
+      summary: List dependencies of an MCP server
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries. Returns `{}` when no dependents exist, including for
+        well-formatted but nonexistent IDs.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/mcpservers/{_id}/effective-access:
+    get:
+      x-internal: false
+      summary: Get effective end-user access for an MCP server
+      operationId: getMcpServerEffectiveAccess
+      tags:
+        - MCP Servers
+      description: |-
+        Server-scoped reverse lookup: finds every end user who can reach this MCP
+        server and compiles each one's effective tool access with source
+        attribution — the union of direct grants, group grants, role grants, and
+        permission sets. The result is recomputed on every request rather than
+        cached. Requires account owner or administrator access. The per-user view
+        of the same compilation is `GET /v1/endusers/{_ashareId}/effective-access`
+        (End Users API).
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      responses:
+        '200':
+          description: Compiled effective access by end user.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServerEffectiveAccess'
+              examples:
+                default:
+                  summary: One end user with permission-set access
+                  value:
+                    _mcpServerId: 69eb9fb5b4fc023618e490b8
+                    serverName: Customer Integration MCP
+                    users:
+                      - _ashareId: 68b1c2d3e4f5a6b7c8d9e0f1
+                        _userId: 624774a6a7574d3ed9f9a5cc
+                        email: jane.doe@example.com
+                        name: Jane Doe
+                        tools:
+                          - _id: 69d462d5b9c28ea0b7f82522
+                            name: get_customer
+                            via:
+                              - pset:Finance read-only (group:Finance)
+                no_access:
+                  summary: No end user has access to this server
+                  value:
+                    _mcpServerId: 69eb9fb5b4fc023618e490b8
+                    serverName: Customer Integration MCP
+                    users: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/mcpservers/{_id}/endusers:
+    put:
+      x-internal: false
+      summary: Bulk assign MCP server access to end users
+      operationId: assignMcpServerEndUsers
+      tags:
+        - MCP Servers
+      description: |-
+        Assigns this server's capabilities to up to 100 end users in one request.
+        For each end user, the grant for this server is replaced with the supplied
+        capabilities; grants for other MCP servers and wildcard grants are
+        preserved. End users whose grants already match are counted as processed
+        without a save. Processing stops at the first failure — the response then
+        carries the entries completed before it, plus `errors`. Requires account
+        owner or administrator access.
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkAssignEndUsersRequest'
+            examples:
+              pset_grant:
+                summary: Grant a permission set to two end users
+                value:
+                  _ashareIds:
+                    - 68b1c2d3e4f5a6b7c8d9e0f1
+                    - 68b1c2d3e4f5a6b7c8d9e0f2
+                  capabilities:
+                    - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+              all_tools:
+                summary: Grant every tool on the server
+                value:
+                  _ashareIds:
+                    - 68b1c2d3e4f5a6b7c8d9e0f1
+                  capabilities:
+                    - tool:all
+      responses:
+        '200':
+          description: All end users processed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkAssignEndUsersResult'
+              examples:
+                default:
+                  value:
+                    updated: 2
+                    _mcpServerId: 69eb9fb5b4fc023618e490b8
+                    serverName: Customer Integration MCP
+                    endUsers:
+                      - _id: 68b1c2d3e4f5a6b7c8d9e0f1
+                        _sharedWithUserId: 624774a6a7574d3ed9f9a5cc
+                        resourceGrants:
+                          - resourceType: mcpServer
+                            _resourceId: 69eb9fb5b4fc023618e490b8
+                            capabilities:
+                              - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+                        capabilities:
+                          - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+                      - _id: 68b1c2d3e4f5a6b7c8d9e0f2
+                        _sharedWithUserId: 624774a6a7574d3ed9f9a5dd
+                        resourceGrants:
+                          - resourceType: mcpServer
+                            _resourceId: 69eb9fb5b4fc023618e490b8
+                            capabilities:
+                              - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+                        capabilities:
+                          - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+        '400':
+          description: |-
+            Validation failed. Pre-flight failures (invalid MCP server id,
+            invalid request body, unknown end-user ids) return a bare `errors`
+            array; a mid-batch failure from merged-grant re-validation returns
+            the result body with partial progress plus `errors`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                too_many:
+                  value:
+                    errors:
+                      - code: validation_failed
+                        message: Validation failed. _ashareIds cannot exceed 100 entries per request.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: |-
+            MCP server not found in this account (pre-flight, a bare `errors`
+            array), or an end-user share disappeared mid-batch (the result body
+            with partial progress plus `errors`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                server_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: MCP server not found in this account.
+        '409':
+          description: |-
+            A duplicate end-user share was detected while persisting mid-batch
+            (`enduser_ashare_exists`). Returns the result body with partial
+            progress plus `errors`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkAssignEndUsersResult'
+  /v1/mcpservers/{_id}/groups:
+    put:
+      x-internal: false
+      summary: Bulk assign MCP server access to groups
+      operationId: assignMcpServerGroups
+      tags:
+        - MCP Servers
+      description: |-
+        Assigns this server's capabilities to up to 100 groups in one request.
+        For each group, the grant for this server is replaced with the supplied
+        capabilities; grants for other MCP servers and wildcard grants are
+        preserved, and the group's roles and members are not changed. Groups are
+        updated in batches of five; processing stops at the first failure — the
+        response then carries the groups completed before it, plus `errors`.
+        Requires account owner or administrator access.
+      parameters:
+        - name: _id
+          in: path
+          description: MCP server ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkAssignGroupsRequest'
+            examples:
+              pset_grant:
+                summary: Grant a permission set to two groups
+                value:
+                  _groupIds:
+                    - 68a1b2c3d4e5f6a7b8c9d0e1
+                    - 68a1b2c3d4e5f6a7b8c9d0e2
+                  capabilities:
+                    - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+              all_tools:
+                summary: Grant every tool on the server
+                value:
+                  _groupIds:
+                    - 68a1b2c3d4e5f6a7b8c9d0e1
+                  capabilities:
+                    - tool:all
+      responses:
+        '200':
+          description: All groups processed. `groups` is sorted by group name.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkAssignGroupsResult'
+              examples:
+                default:
+                  value:
+                    updated: 2
+                    _mcpServerId: 69eb9fb5b4fc023618e490b8
+                    serverName: Customer Integration MCP
+                    groups:
+                      - _id: 68a1b2c3d4e5f6a7b8c9d0e1
+                        name: Finance
+                        _roleIds:
+                          - 68c1d2e3f4a5b6c7d8e9f0a1
+                        capabilities:
+                          - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+                      - _id: 68a1b2c3d4e5f6a7b8c9d0e2
+                        name: Operations
+                        _roleIds: []
+                        capabilities:
+                          - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+        '400':
+          description: |-
+            Validation failed. Pre-flight failures (invalid MCP server id,
+            invalid request body, more than 100 or duplicate `_groupIds`, unknown
+            group ids, capabilities that do not resolve on this server) return a
+            bare `errors` array; a mid-batch failure returns the result body with
+            partial progress plus `errors`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                too_many:
+                  value:
+                    errors:
+                      - code: validation_failed
+                        message: Validation failed. _groupIds cannot exceed 100 entries per request.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: MCP server not found in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                server_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: MCP server not found in this account.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    Annotations:
+      type: object
+      description: |
+        MCP-standard annotations that hint at the behavior of a tool.
+
+        These annotations follow the Model Context Protocol specification and help
+        AI agents and MCP clients understand how a tool behaves without executing it.
+        All fields are optional hints — they are not enforced by the server.
+      properties:
+        title:
+          type: string
+          maxLength: 300
+          description: |
+            Human-readable title for the tool, displayed in MCP client UIs.
+
+            If not provided, the tool's `name` field is used instead.
+          examples:
+            - Create Customer Record
+            - Fetch Order Status
+        destructiveHint:
+          type: boolean
+          description: |
+            Hints that the tool may perform destructive operations such as
+            deleting or permanently modifying data.
+          examples:
+            - true
+            - false
+        idempotentHint:
+          type: boolean
+          description: |
+            Hints that calling the tool multiple times with the same input
+            produces the same result without additional side effects.
+          examples:
+            - true
+            - false
+        openWorldHint:
+          type: boolean
+          description: |
+            Hints that the tool interacts with an open-world environment
+            (e.g., external APIs) where results may vary between calls.
+          examples:
+            - true
+            - false
+        readOnlyHint:
+          type: boolean
+          description: |
+            Hints that the tool only reads data and does not modify any state.
+          examples:
+            - true
+            - false
+    Overrides:
+      type: object
+      description: |
+        Per-server overrides for a tool's internal resources.
+
+        When a tool is added to an MCP server, its connections, exports, imports,
+        and routers can be customized for this specific server context without
+        modifying the underlying tool definition. This enables reusing the same
+        tool across multiple MCP servers with different configurations.
+      properties:
+        connections:
+          type: array
+          description: |
+            Connection overrides. Each entry maps an abstract connection reference
+            in the tool to a concrete connection resource for this server.
+          items:
+            type: object
+            properties:
+              _abstractId:
+                type: string
+                description: |
+                  The abstract connection identifier from the tool definition.
+                  This is the connection reference that will be replaced.
+                examples:
+                  - 60a2c4e6f321d800129a1a3c
+              _id:
+                type: string
+                x-celigo-refModel: connections
+                format: objectId
+                description: |
+                  The concrete connection resource to use in place of the abstract reference.
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              _borrowConcurrencyFromConnectionId:
+                type: string
+                x-celigo-refModel: connections
+                description: |
+                  Optional connection from which to borrow concurrency limits.
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+            required:
+              - _abstractId
+        exports:
+          type: array
+          description: |
+            Export (lookup) overrides. Customize export resources used within the tool,
+            including connection bindings, scheduling, response mappings, and
+            adaptor-specific settings.
+          items:
+            type: object
+            properties:
+              _abstractId:
+                type: string
+                description: Abstract export identifier from the tool definition
+                examples:
+                  - 60a2c4e6f321d800129a1a3c
+              _id:
+                type: string
+                x-celigo-refModel: exports
+                format: objectId
+                description: Concrete export resource to use
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              _connectionId:
+                type: string
+                x-celigo-refModel: connections
+                format: objectId
+                description: Override the connection used by this export
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              type:
+                type: string
+                enum:
+                  - webhook
+                  - distributed
+                  - test
+                  - delta
+                  - once
+                  - tranlinedelta
+                  - simple
+                  - blob
+                  - all
+                x-enumDescriptions:
+                  webhook: Event-driven export triggered by incoming webhook calls.
+                  distributed: Export distributed across multiple NetSuite worker nodes.
+                  test: Export used for testing and validation only.
+                  delta: Incremental export that fetches only records changed since the last run.
+                  once: One-time export that runs a single time and does not repeat.
+                  tranlinedelta: Transaction line-level delta export for NetSuite transaction lines.
+                  simple: Basic export that fetches all matching records on each run.
+                  blob: Binary large object export for file-based data.
+                  all: Export that retrieves all records without filtering.
+                description: Override the export type
+              pageSize:
+                type: number
+                description: Override the page size for pagination
+                examples:
+                  - 100
+              skipRetries:
+                type: boolean
+                description: When true, skips retries on failure.
+                x-celigo-ai-guidance:
+                  - Whether to skip retries on failure
+              proceedOnFailure:
+                type: boolean
+                description: When true, continues processing subsequent records after a failure.
+                x-celigo-ai-guidance:
+                  - Whether to continue processing on failure
+              responseMapping:
+                type: object
+                description: Override the response field mappings
+                properties:
+                  fields:
+                    type: array
+                    description: Field-level mappings that copy individual values from the response back onto the record.
+                    items:
+                      type: object
+                      properties:
+                        extract:
+                          type: string
+                          description: Path in the response to extract the value from. Uses dot notation to navigate nested objects.
+                          examples:
+                            - data.id
+                        generate:
+                          type: string
+                          description: Target field path on the record where the extracted value is stored.
+                          examples:
+                            - customerId
+                  lists:
+                    type: array
+                    description: Array-level mappings for one-to-many data in the response.
+                    items:
+                      type: object
+                      properties:
+                        generate:
+                          type: string
+                          description: Target array field on the record where the mapped list items are stored.
+                          examples:
+                            - lineItems
+                        fields:
+                          type: array
+                          description: Field mappings applied to each item in the response array.
+                          items:
+                            type: object
+                            properties:
+                              extract:
+                                type: string
+                                description: Path within each response list item to extract the value from.
+                                examples:
+                                  - sku
+                              generate:
+                                type: string
+                                description: Target field path within each mapped list item.
+                                examples:
+                                  - itemCode
+            required:
+              - _abstractId
+        imports:
+          type: array
+          description: |
+            Import overrides. Customize import resources used within the tool,
+            including connection bindings, hooks, response mappings, and
+            adaptor-specific settings.
+          items:
+            type: object
+            properties:
+              _abstractId:
+                type: string
+                description: Abstract import identifier from the tool definition
+                examples:
+                  - 60a2c4e6f321d800129a1a3c
+              _connectionId:
+                type: string
+                x-celigo-refModel: connections
+                format: objectId
+                description: Override the connection used by this import
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              proceedOnFailure:
+                type: boolean
+                description: When true, continues processing subsequent records after a failure.
+                x-celigo-ai-guidance:
+                  - Whether to continue processing on failure
+              responseMapping:
+                type: object
+                description: Override the response field mappings
+                properties:
+                  fields:
+                    type: array
+                    description: Field-level mappings that copy individual values from the response back onto the record.
+                    items:
+                      type: object
+                      properties:
+                        extract:
+                          type: string
+                          description: Path in the response to extract the value from. Uses dot notation to navigate nested objects.
+                          examples:
+                            - data.id
+                        generate:
+                          type: string
+                          description: Target field path on the record where the extracted value is stored.
+                          examples:
+                            - customerId
+                  lists:
+                    type: array
+                    description: Array-level mappings for one-to-many data in the response.
+                    items:
+                      type: object
+                      properties:
+                        generate:
+                          type: string
+                          description: Target array field on the record where the mapped list items are stored.
+                          examples:
+                            - lineItems
+                        fields:
+                          type: array
+                          description: Field mappings applied to each item in the response array.
+                          items:
+                            type: object
+                            properties:
+                              extract:
+                                type: string
+                                description: Path within each response list item to extract the value from.
+                                examples:
+                                  - sku
+                              generate:
+                                type: string
+                                description: Target field path within each mapped list item.
+                                examples:
+                                  - itemCode
+              hooks:
+                type: object
+                description: Override script hooks
+                properties:
+                  preMap:
+                    type: object
+                    description: Hook that runs on each page of records before the import's mappings are applied.
+                    properties:
+                      function:
+                        type: string
+                        description: Function to invoke within the referenced script.
+                        examples:
+                          - preMap
+                      _scriptId:
+                        type: string
+                        x-celigo-refModel: scripts
+                        format: objectId
+                        description: Script containing the hook function named in `function`.
+                        examples:
+                          - 66a1f2c3b4d5e6f7a8b9c0d1
+                  postMap:
+                    type: object
+                    description: |-
+                      Hook that runs after the import's mappings are applied but before records
+                      are sent to the destination system.
+                    properties:
+                      function:
+                        type: string
+                        description: Function to invoke within the referenced script.
+                        examples:
+                          - postMap
+                      _scriptId:
+                        type: string
+                        x-celigo-refModel: scripts
+                        format: objectId
+                        description: Script containing the hook function named in `function`.
+                        examples:
+                          - 66a1f2c3b4d5e6f7a8b9c0d2
+            required:
+              - _abstractId
+        routers:
+          type: array
+          description: |
+            Router overrides. Customize routing behavior for specific branches
+            within the tool, including branch filters and routing strategies.
+          items:
+            type: object
+            properties:
+              _abstractId:
+                type: string
+                description: Abstract router identifier from the tool definition
+                examples:
+                  - router_001
+              name:
+                type: string
+                description: Override the router name
+                examples:
+                  - route_by_region
+              routeRecordsTo:
+                type: string
+                enum:
+                  - first_matching_branch
+                  - all_matching_branches
+                x-enumDescriptions:
+                  first_matching_branch: Routes each record to only the first branch whose criteria match.
+                  all_matching_branches: Routes each record to every branch whose criteria match, creating copies.
+                description: Override the routing strategy
+              routeRecordsUsing:
+                type: string
+                enum:
+                  - input_filters
+                  - script
+                x-enumDescriptions:
+                  input_filters: Evaluate routing criteria using declarative filter expressions.
+                  script: Evaluate routing criteria using a custom JavaScript function.
+                description: Override the routing evaluation method
+              script:
+                type: object
+                description: Override the router script
+                properties:
+                  _scriptId:
+                    type: string
+                    x-celigo-refModel: scripts
+                    format: objectId
+                    description: Script containing the routing function named in `function`.
+                    examples:
+                      - 66a1f2c3b4d5e6f7a8b9c0d3
+                  function:
+                    type: string
+                    description: Function within the referenced script that returns the name of the branch to route to.
+                    examples:
+                      - routeRecord
+              branches:
+                type: array
+                description: Override specific branch configurations
+                items:
+                  type: object
+                  properties:
+                    _abstractId:
+                      type: string
+                      description: Abstract branch identifier
+                    name:
+                      type: string
+                      description: Override the branch name
+                      examples:
+                        - North America
+                    description:
+                      type: string
+                      description: Override the branch description
+                      examples:
+                        - Records routed to the North America region
+                    inputFilter:
+                      type: object
+                      description: Override the branch filter criteria
+                      properties:
+                        version:
+                          type: string
+                          enum:
+                            - '1'
+                          x-enumDescriptions:
+                            '1': Version 1 of the Celigo expression-based filter format.
+                          description: Filter format version.
+                        rules:
+                          type: array
+                          description: |-
+                            Filter rules in Celigo expression-based filter format. Array-based DSL where
+                            the first element is an operator (e.g. "equals", "and", "or"), followed by
+                            operands which can be nested expressions.
+                          items: {}
+            required:
+              - _abstractId
+    IOTool:
+      type: object
+      description: |-
+        A tool entry that maps a Celigo Tool resource to an MCP tool endpoint.
+        The referenced tool's input schema must have `type: "object"`.
+      x-celigo-ai-guidance:
+        - |-
+          A tool entry within an MCP server references a Tool resource;
+          tool names across all tools and APIs within the same MCP server must be unique
+          and follow the MCP naming convention (alphanumeric,
+          underscores, hyphens, dots only).
+      properties:
+        _toolId:
+          type: string
+          x-celigo-refModel: tools
+          format: objectId
+          description: |-
+            Tool resource ID. The referenced tool must exist and have an
+            input schema with `type: "object"`.
+          x-celigo-ai-guidance:
+            - Reference to the Tool resource that this MCP tool exposes.
+          examples:
+            - 69d462d5b9c28ea0b7f82522
+        name:
+          type: string
+          maxLength: 128
+          pattern: ^[A-Za-z0-9_\-.]+$
+          description: |-
+            MCP tool name exposed to clients. Must be unique across all tools
+            and APIs within this server.
+          x-celigo-ai-guidance:
+            - |-
+              Must be unique across all tools and APIs within this MCP server.
+              Only alphanumeric characters, underscores, hyphens, and dots are allowed.
+              Maximum length: 128 characters (enforced by validation).
+          examples:
+            - get_customer
+            - create_order
+            - validate.input
+        disabled:
+          type: boolean
+          default: true
+          description: When true, this tool is disabled and will not be exposed to MCP clients.
+          x-celigo-ai-guidance:
+            - |-
+              Indicates whether this tool is disabled within the MCP server;
+              disabled tools are not exposed to MCP clients.
+              At least one tool, API, resource, or prompt must be enabled for the
+              server itself to be enabled.
+          examples:
+            - false
+            - true
+        annotations:
+          $ref: '#/components/schemas/Annotations'
+        overrides:
+          $ref: '#/components/schemas/Overrides'
+      required:
+        - _toolId
+        - name
+    ApiTool:
+      type: object
+      description: |-
+        An API entry that maps a Celigo builder-mode API resource to an MCP
+        tool endpoint. Script-type APIs are not supported.
+      x-celigo-ai-guidance:
+        - |-
+          Each API tool maps a Celigo API to an MCP-compatible tool endpoint;
+          only builder-type APIs (not script-type) can be used in MCP servers.
+        - |-
+          Tool names across all tools and APIs within the same MCP server must be unique
+          and follow the MCP naming convention:
+          alphanumeric characters, underscores, hyphens, and dots only.
+      properties:
+        name:
+          type: string
+          maxLength: 128
+          pattern: ^[A-Za-z0-9_\-.]+$
+          description: |-
+            MCP tool name exposed to clients. Must be unique across all tools
+            and APIs within this server.
+          x-celigo-ai-guidance:
+            - |-
+              Must be unique across all tools and APIs within this MCP server.
+              Only alphanumeric characters, underscores, hyphens, and dots are allowed.
+              Maximum length: 128 characters (enforced by validation).
+          examples:
+            - customer_api
+            - order.lookup
+        _apiId:
+          type: string
+          x-celigo-refModel: apis
+          format: objectId
+          description: API resource ID. Must reference a builder-type API (not script-type).
+          x-celigo-ai-guidance:
+            - |-
+              The referenced API resource exposed by this MCP tool must exist,
+              belong to the same user, and be of type "builder";
+              script-type APIs are not supported.
+          examples:
+            - 68ae4264b5f755d2dd3796b4
+        disabled:
+          type: boolean
+          default: true
+          description: When true, this API tool is disabled and will not be exposed to MCP clients.
+          x-celigo-ai-guidance:
+            - Whether this API tool is disabled within the MCP server.
+          examples:
+            - false
+            - true
+      required:
+        - name
+        - _apiId
+    McpResource:
+      type: object
+      description: |-
+        A resource entry that exposes a Celigo Storage file to MCP clients.
+        Clients discover resources via `resources/list` and fetch file content
+        via `resources/read`. Resources are not supported on sandbox servers —
+        setting `resources` together with `sandbox: true` returns 422
+        `mcp_server_resources_not_allowed_in_sandbox`.
+      x-celigo-ai-guidance:
+        - |-
+          Each resource entry references a file in Celigo Storage (a StorageItem);
+          the file must exist, be an active file (not a folder), and belong to the
+          same account — otherwise the create or update fails with 422
+          "mcp_server_file_not_found" on the offending "resources.N._fileId".
+        - |-
+          Do not set resources on a sandbox MCP server; the API rejects the
+          request with 422 "mcp_server_resources_not_allowed_in_sandbox".
+      properties:
+        title:
+          type: string
+          maxLength: 250
+          description: |-
+            Human-readable display title shown to MCP clients alongside the
+            file. Free text, unlike tool and API names (which are
+            regex-constrained MCP identifiers).
+          examples:
+            - Return Policy
+            - Product Catalog 2026
+        _fileId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Celigo Storage file exposed by this resource. Must reference an
+            active file (not a folder) owned by the account — invalid references
+            return 422 `mcp_server_file_not_found`. Each file can be referenced
+            only once per server; duplicates return 422
+            `mcp_server_duplicate_file_not_allowed`. Manage files via
+            `GET /v1/storage/items`.
+          x-celigo-ai-guidance:
+            - |-
+              Reference an existing Celigo Storage file id (see GET /v1/storage/items);
+              folder ids and unknown ids fail with 422 "mcp_server_file_not_found",
+              and the same file id may appear only once across resources[].
+          examples:
+            - 6a55886da387d16e4e475aa2
+        disabled:
+          type: boolean
+          default: true
+          description: |-
+            When true, the resource is hidden from MCP clients and its file is
+            not served. Resources are disabled by default; set to false to
+            expose the file.
+          examples:
+            - false
+            - true
+      required:
+        - _fileId
+    PromptArgument:
+      type: object
+      description: |
+        A single declared argument for a prompt. Argument names appear as
+        `{{name}}` placeholders inside `messagesTemplate[*].template` and are
+        substituted with client-supplied values at invocation time.
+      properties:
+        name:
+          type: string
+          maxLength: 256
+          pattern: ^\w+$
+          description: |
+            Argument name. Must match `^\\w+$` (letters, digits, and underscores
+            only) so it can be referenced as a Handlebars `{{placeholder}}` in the
+            message template. Hyphens, dots, and other characters are not allowed
+            here (even though prompt `name` permits them) — they would break the
+            template parser.
+          examples:
+            - meeting_date
+            - transcript
+            - ticket_id
+        description:
+          type: string
+          maxLength: 1000
+          description: |
+            Optional human-readable description of the argument. Shown to MCP
+            clients during discovery; useful for guiding LLMs that supply values.
+          examples:
+            - The date the meeting occurred (YYYY-MM-DD).
+        required:
+          type: boolean
+          default: true
+          description: |
+            Whether the client must supply this argument. Defaults to `true`.
+            When `false`, the client may omit the argument and the
+            `{{placeholder}}` is left empty after substitution.
+          examples:
+            - true
+            - false
+      required:
+        - name
+    PromptMessage:
+      type: object
+      description: |
+        A single message entry inside a prompt's `messagesTemplate[]`. Renders to
+        a `{role, content: {type, text|data, mimeType?}}` object in the
+        `prompts/get` response after Handlebars substitution.
+      properties:
+        role:
+          type: string
+          enum:
+            - user
+            - assistant
+          x-enumDescriptions:
+            user: Message from the user or human participant.
+            assistant: Message from the AI assistant.
+          description: |
+            Message role exposed to MCP clients.
+
+            Only `user` and `assistant` are supported. `system` role messages are
+            not allowed at this layer — express system-level intent inside the
+            first user or assistant template.
+          examples:
+            - user
+            - assistant
+        contentType:
+          type: string
+          enum:
+            - text
+            - image
+            - audio
+            - resource
+          x-enumDescriptions:
+            text: Plain text content.
+            image: Binary image content (requires mimeType).
+            audio: Binary audio content (requires mimeType).
+            resource: Reference to an external resource.
+          default: text
+          description: |
+            Type of content this message carries.
+
+            - `text` — `template` holds the Handlebars-templated text body.
+            - `image` / `audio` — `data` (base64) and `mimeType` are required
+              (omitting `mimeType` returns 422 `mcp_server_prompt_mimetype_required`);
+              `template` is not used.
+            - `resource` — reserved for future use; the authoring UI does not
+              currently expose this option.
+          examples:
+            - text
+            - image
+        template:
+          type: string
+          maxLength: 4096
+          description: |
+            Handlebars-templated text body. Use `{{argumentName}}` to reference
+            declared arguments — they are substituted server-side before the
+            message is returned to the client.
+
+            Up to 4 KB inline. Templates larger than 4 KB are automatically
+            offloaded to S3 (up to a 1 MB hard limit) and rehydrated on read.
+
+            Only relevant when `contentType` is `text` (the default).
+          examples:
+            - |-
+              Summarize the {{meeting_title}} meeting held on {{meeting_date}}:
+
+              {{transcript}}
+        data:
+          type: string
+          description: |
+            Base64-encoded binary content for image / audio messages. Only allowed
+            when `contentType` is `image` or `audio`.
+
+            Up to 10 MB via S3 offload.
+        mimeType:
+          type: string
+          maxLength: 100
+          description: |
+            MIME type for the binary `data`. Required when `contentType` is `image`
+            or `audio` (e.g. `image/png`, `audio/wav`).
+          examples:
+            - image/png
+            - image/jpeg
+            - audio/wav
+      required:
+        - role
+    Prompt:
+      type: object
+      description: |
+        A prompt template entry on an MCP server.
+
+        Prompts are inline, reusable templates that MCP-compatible clients (Claude,
+        Cursor, Celigo AI Agents, etc.) discover via `prompts/list` and fetch via
+        `prompts/get`. Each `{{placeholder}}` inside a message template becomes a
+        declared argument that the client supplies at invocation time; the
+        backend performs Handlebars substitution before returning the rendered
+        messages.
+
+        Unlike `tools[]` and `apis[]` — which reference other Celigo resources by
+        ID — a prompt is stored inline on the MCP server document. There is no
+        separate "Prompt" resource type.
+
+        `prompts/get` returns rendered messages of shape
+        `[{role, content: {type, text | data, mimeType?}}]` — `text` for `text`
+        content, or `data` (base64) + `mimeType` for `image`/`audio`. This schema
+        captures the stored template; the rendered output is not part of the
+        persisted document.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: |
+            Server-generated identifier for the prompt — the grant handle
+            referenced as `tool:<_id>` in end-user, group, and role resource
+            grants. Identity is preserved across updates by matching on `name`,
+            so renaming a prompt assigns a new `_id` and breaks grants that
+            reference the old one.
+          examples:
+            - 6b2c3d4e5f6a7b8c9d0e1f2a
+        name:
+          type: string
+          maxLength: 128
+          pattern: ^[A-Za-z0-9_\-.]+$
+          description: |
+            MCP prompt name exposed to clients via `prompts/list`.
+
+            Must be unique within `prompts[]` on this server. Only alphanumeric
+            characters, underscores, hyphens, and dots are allowed. Prompts have
+            their own namespace — a prompt named `summarize_meeting` does not
+            collide with a tool or API of the same name.
+
+            Maximum length: 128 characters. Duplicate names return 422
+            `mcp_server_duplicate_prompt_name`.
+          examples:
+            - summarize_meeting
+            - draft_email
+            - review.checklist
+        title:
+          type: string
+          maxLength: 1000
+          description: |
+            Human-readable display title shown alongside `name` in MCP clients.
+
+            Unlike `name` (the MCP identifier, regex-constrained), `title` is
+            free text. Optional — clients fall back to `name` when omitted.
+          examples:
+            - Summarize Meeting
+            - Draft Professional Email
+        description:
+          type: string
+          maxLength: 1000
+          description: |
+            Optional description of what the prompt does. Shown to MCP clients
+            during discovery so users and LLMs can choose the right prompt.
+          examples:
+            - Summarize a meeting transcript into key decisions and action items.
+        arguments:
+          type: array
+          description: |
+            Declared arguments for the prompt. Every `{{placeholder}}` referenced
+            in `messagesTemplate[*].template` should appear here so MCP clients
+            know what to supply when invoking the prompt.
+          items:
+            $ref: '#/components/schemas/PromptArgument'
+        messagesTemplate:
+          type: array
+          description: |
+            Ordered list of message templates forming the prompt body. At least
+            one entry is required. Each entry renders to a single message after
+            Handlebars substitution.
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/PromptMessage'
+        mockInput:
+          type: object
+          description: |
+            Sample argument values used to preview / test-run the prompt in the
+            authoring UI — a plain object mapping argument names to sample values
+            (e.g. `{"username": "John Doe"}`). Keys usually mirror `arguments[].name`
+            but this is not enforced. Has no effect on `prompts/get` rendering for
+            MCP clients.
+          examples:
+            - username: John Doe
+        disabled:
+          type: boolean
+          default: true
+          description: |-
+            When true, the prompt is hidden from MCP clients — omitted from
+            `prompts/list` and not fetchable via `prompts/get`. New prompts
+            default to disabled; set to false to expose the prompt. An enabled
+            prompt also satisfies the server-level enablement rule on its own.
+            Prompts saved before this field existed are reported as
+            `disabled: false`.
+          examples:
+            - false
+            - true
+      required:
+        - name
+        - messagesTemplate
+    PermissionSet:
+      type: object
+      description: |-
+        A named bundle of this server's tools and APIs — shown as a "Capability
+        Set" in the integrator.io UI — granted to end users as one unit through
+        the `pset:<_id>` capability string on end-user, group, and role resource
+        grants. There is no standalone permission-set resource: sets live only
+        inside the MCP server document, and each set's `_id` is the stable handle
+        that grants reference.
+
+        Deleting a set — or resubmitting it without its `_id` — rewrites every
+        grant that references it: the `pset:` capability is replaced with the
+        set's constituent `tool:`/`api:` capabilities at removal time.
+      x-celigo-ai-guidance:
+        - |-
+          When updating a server via PUT, send the complete `permissionSets` array
+          and round-trip every existing set with its `_id` intact — an omitted set
+          is removed and the grants that referenced it are flattened to its
+          individual tool/API capabilities.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: |-
+            Server-generated identifier for the set — the grant handle referenced
+            as `pset:<_id>` in resource grants. Send it back unchanged on PUT to
+            preserve the set's identity; a set submitted without its `_id` is
+            treated as a brand-new set and assigned a fresh one.
+          examples:
+            - 6a7b8c9d0e1f2a3b4c5d6e7f
+        name:
+          type: string
+          maxLength: 300
+          description: |-
+            Display name for the set. Must be unique per server,
+            case-insensitively — duplicates are rejected with 422.
+          examples:
+            - Finance read-only
+            - Order management
+        description:
+          type: string
+          maxLength: 1000
+          description: Description of what the set grants and who it is for.
+          examples:
+            - Read-only invoice lookups for the finance team
+        accessLevel:
+          type: string
+          enum:
+            - read
+            - write
+          x-enumDescriptions:
+            read: Read-level access, aligned with the `mcp:read` OAuth scope
+            write: Write-level access, aligned with the `mcp:write` OAuth scope
+          description: OAuth-aligned access level the set pins for everyone it is granted to.
+          examples:
+            - read
+        _toolIds:
+          type: array
+          description: |-
+            Tool resources included in the set. Every entry must reference a tool
+            already attached to this server through `tools[]._toolId` —
+            referencing one that is not attached is rejected with 422.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+          examples:
+            - - 69d462d5b9c28ea0b7f82522
+        _apiIds:
+          type: array
+          description: |-
+            Builder-mode API resources included in the set. Every entry must
+            reference an API already attached to this server through
+            `apis[]._apiId` — referencing one that is not attached is rejected
+            with 422.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+          examples:
+            - - 68ae4264b5f755d2dd3796b4
+      required:
+        - name
+        - accessLevel
+    OAuthConfig:
+      type: object
+      description: |-
+        OAuth 2.0 configuration for the MCP server. Three modes are supported:
+
+        **Celigo-managed OAuth** — set `useCeligoOauth: true`. No issuer or
+        audience configuration needed; Celigo handles token validation.
+
+        **OAuth provider reference** — set `_mcpOAuthProviderId` to the ID of
+        a shared MCP OAuth provider resource (see `/v1/mcpoauthproviders`).
+        The provider holds the issuer, audience, and introspection settings.
+
+        **Inline custom OAuth** — set `issuerURL` and `audience` directly.
+        Tokens are validated against the issuer's JWKS. Optionally enable
+        `useIntrospection` for opaque tokens via RFC 7662.
+
+        Omit `oauth` entirely (or send `{}`) to disable OAuth on the server.
+        In responses, `oauth` is absent when no OAuth mode is configured.
+        The three modes are mutually exclusive. When using inline custom
+        OAuth, both `issuerURL` and `audience` are required. When
+        `useIntrospection` is `true`, `clientId` is also required.
+      properties:
+        useCeligoOauth:
+          type: boolean
+          description: |-
+            When `true`, enables Celigo-managed OAuth. No external issuer
+            configuration is needed. Mutually exclusive with
+            `_mcpOAuthProviderId` and inline OAuth fields.
+        _mcpOAuthProviderId:
+          type: string
+          format: objectId
+          x-celigo-refModel: mcpoauthproviders
+          description: |-
+            References a shared MCP OAuth provider resource that holds the
+            issuer, audience, scopes, and introspection settings. Mutually
+            exclusive with `useCeligoOauth` and inline OAuth fields.
+
+            Use `GET /v1/mcpoauthproviders` to list available providers.
+        issuerURL:
+          type: string
+          format: uri
+          description: |-
+            OAuth 2.0 issuer URL for inline custom OAuth.
+
+            Must be a well-formed URL with an explicit scheme — bare hostnames
+            and protocol-less values are rejected with 422 `invalid_uri`.
+            Use `https://` for production issuers.
+          examples:
+            - https://auth.example.com
+        audience:
+          type: string
+          description: |-
+            Expected `aud` claim on incoming access tokens. Required when
+            using inline custom OAuth — omitting it returns
+            `missing_required_field` on `oauth.audience`.
+          examples:
+            - https://mcp.example.com
+        useIntrospection:
+          type: boolean
+          default: false
+          description: |-
+            When `true`, opaque access tokens are validated by calling the
+            issuer's RFC 7662 introspection endpoint using `clientId` /
+            `clientSecret`. When `false`, only JWT access tokens are accepted.
+        scopes:
+          type: array
+          description: |-
+            Required OAuth scopes. Incoming tokens must carry every listed scope.
+
+            Rejected values return `enum` / `invalid_field_value` on
+            `oauth.scopes.<index>`.
+          items:
+            type: string
+            enum:
+              - mcp:read
+              - mcp:write
+            x-enumDescriptions:
+              mcp:read: Grants read-only access to MCP server resources.
+              mcp:write: Grants write access to MCP server resources.
+          examples:
+            - - mcp:read
+              - mcp:write
+        clientId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            OAuth client ID used when introspecting opaque tokens. Required
+            when `useIntrospection` is `true`.
+        clientSecret:
+          type:
+            - string
+            - 'null'
+          description: |-
+            OAuth client secret used with `clientId` for introspection. Masked
+            as `"******"` in response payloads; sending the masked value on
+            PUT is treated as "leave unchanged".
+      dependentRequired:
+        issuerURL:
+          - audience
+        audience:
+          - issuerURL
+      if:
+        properties:
+          useIntrospection:
+            const: true
+        required:
+          - useIntrospection
+      then:
+        required:
+          - clientId
+    MCPServerBase:
+      type: object
+      description: Writable MCP server fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 150
+          description: Display name for the MCP server.
+          x-celigo-ai-guidance:
+            - Displayed in the UI to identify the server's purpose.
+          examples:
+            - Customer Integration MCP
+            - Order Processing Server
+        relativeURI:
+          type: string
+          maxLength: 131072
+          pattern: ^\/[a-zA-Z0-9_\-]+$
+          description: |-
+            URI path segment for the MCP server endpoint. Must be unique per account —
+            duplicates are rejected with 422 `mcp_server_duplicate_relative_uri`. Only letters,
+            numbers, dashes, and underscores after the leading slash (the server's error message
+            also claims colons and dots are allowed, but they are rejected in practice). Creation
+            also requires the account to have an account alias set (422
+            `mcp_server_account_alias_required` otherwise).
+          x-celigo-ai-guidance:
+            - |-
+              Set the field to a unique pathname per account that starts with a forward slash
+              followed by a single path segment containing only alphanumeric characters,
+              underscores, and hyphens.
+            - |-
+              If not provided,
+              a `url` field can be supplied instead and the pathname will be extracted automatically.
+          examples:
+            - /customers
+            - /order-processing
+            - /crm_tools
+        description:
+          type: string
+          maxLength: 1000
+          description: Description of the MCP server's purpose.
+          x-celigo-ai-guidance:
+            - Optional description of the MCP server's purpose and capabilities.
+          examples:
+            - Exposes customer management tools for AI agent consumption
+        disabled:
+          type: boolean
+          default: true
+          description: |-
+            Whether the MCP server is disabled. Defaults to `true` on creation.
+            To serve requests, at least one tool, API, resource, or prompt must
+            also be enabled.
+          x-celigo-ai-guidance:
+            - |-
+              Disabled servers are not accessible to MCP clients.
+              To enable a server, at least one tool or API within it must also be enabled.
+          examples:
+            - false
+            - true
+        tools:
+          type: array
+          description: |-
+            Tool entries referencing Celigo Tool resources. Duplicate `_toolId`
+            values are rejected. Names must be unique across both `tools` and `apis`.
+          x-celigo-ai-guidance:
+            - |-
+              Tool entries reference Celigo Tool resources;
+              each entry exposes a Tool as an MCP tool endpoint.
+            - |-
+              Duplicate `_toolId` references are not allowed,
+              and Tool names must be unique across all tools and APIs in the server.
+          items:
+            $ref: '#/components/schemas/IOTool'
+        apis:
+          type: array
+          description: |-
+            API entries referencing Celigo builder-mode API resources. Only
+            builder-type APIs are supported. Names must be unique across both
+            `tools` and `apis`.
+          x-celigo-ai-guidance:
+            - |-
+              Each entry exposes an API as an MCP tool endpoint.
+              Duplicate `_apiId` references are not allowed.
+              Only builder-type APIs are supported.
+              Tool names must be unique across all tools and APIs in the server.
+          items:
+            $ref: '#/components/schemas/ApiTool'
+        resources:
+          type: array
+          description: |-
+            Files from Celigo Storage exposed to MCP clients as MCP resources.
+            Each entry references a storage file by `_fileId`; the same file can
+            appear only once. Always returned in responses — servers created
+            before resource support return an empty array. Not supported on
+            sandbox servers.
+          x-celigo-ai-guidance:
+            - |-
+              Each resource exposes a Celigo Storage file to MCP clients.
+              The referenced file must exist and belong to the same account,
+              and each _fileId may be used only once per server.
+              Omit the field entirely for sandbox servers — combining
+              resources with sandbox: true fails with 422.
+          items:
+            $ref: '#/components/schemas/McpResource'
+        prompts:
+          type: array
+          description: |-
+            Prompt templates exposed to MCP clients. Each prompt has a unique
+            `name` and may declare `arguments` that clients supply via
+            `prompts/get`.
+          x-celigo-ai-guidance:
+            - |-
+              Unlike `tools` and `apis` (which reference other Celigo resources by ID),
+              each prompt is defined inline on this server.
+              Prompt names have their own namespace — a prompt name may collide with a tool or API name,
+              but must be unique within `prompts[]`.
+          items:
+            $ref: '#/components/schemas/Prompt'
+        permissionSets:
+          type: array
+          description: |-
+            Named bundles of this server's tools and APIs — shown as "Capability
+            Sets" in the UI — granted to end users as a unit via `pset:<_id>`
+            capability strings. Omitting the field on PUT resets it to an empty
+            array, erasing every set and rewriting the grants that reference
+            them — always send the complete array back. Absent from responses for
+            servers not saved since permission sets were introduced (unlike
+            `resources`, the field is not normalized to an empty array).
+          x-celigo-ai-guidance:
+            - |-
+              Not editable via PATCH (the whitelist covers only `/name` and
+              `/disabled`). To change permission sets safely, GET the server,
+              modify `permissionSets`, and PUT the complete document back with
+              every set's `_id` intact.
+          items:
+            $ref: '#/components/schemas/PermissionSet'
+        oauth:
+          $ref: '#/components/schemas/OAuthConfig'
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    MCPServer:
+      type: object
+      required:
+        - _id
+        - name
+        - relativeURI
+        - disabled
+        - createdAt
+        - lastModified
+      description: MCP server object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/MCPServerBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: users
+              description: Owning user ID.
+              examples:
+                - 624cb0346309dc3a543733a2
+            draftExpiresAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: |-
+                When this draft MCP server expires and will be automatically deleted. Only present
+                on servers created as drafts by the AI-assisted builder that have not yet been
+                confirmed. Unlike other resource types, MCP server drafts carry no `draft` boolean —
+                the presence of this field is what marks the draft state.
+              examples:
+                - '2026-05-14T17:16:05.595Z'
+      x-celigo-ai-guidance:
+        - |-
+          Contains the complete MCP server configuration including metadata,
+          tool entries, API entries, and their override settings.
+    Request:
+      type: object
+      description: |-
+        Request body for creating or updating an MCP server. On PUT, include
+        the full `tools`, `apis`, and `resources` arrays because omitted arrays
+        are cleared. Use PATCH to update individual fields without affecting
+        these arrays.
+      x-celigo-ai-guidance:
+        - |-
+          MCP servers expose Celigo tools, builder-mode APIs,
+          and inline prompt templates as MCP-compatible endpoints for consumption by AI
+          agents and MCP clients.
+      required:
+        - name
+        - relativeURI
+      allOf:
+        - $ref: '#/components/schemas/MCPServerBase'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+    MCPServerEffectiveAccess:
+      type: object
+      description: |-
+        The compiled end-user access for one MCP server, with source attribution.
+        Each user's access is the union of their direct grants, group grants,
+        role grants (direct or via groups), and permission sets, recompiled on
+        every request.
+      properties:
+        _mcpServerId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: mcpservers
+          description: MCP server this compilation applies to.
+          examples:
+            - 69eb9fb5b4fc023618e490b8
+        serverName:
+          type:
+            - string
+            - 'null'
+          readOnly: true
+          description: Display name of the MCP server.
+          examples:
+            - Customer Integration MCP
+        users:
+          type: array
+          description: |-
+            End users whose grants compile to tool access on this server. Users
+            whose grants resolve to no enabled tool are omitted, and disabled
+            tools never materialize. An empty array means no end user currently
+            has access.
+          items:
+            type: object
+            properties:
+              _ashareId:
+                type: string
+                format: objectId
+                readOnly: true
+                description: End-user access-record id (from the end users list).
+                examples:
+                  - 68b1c2d3e4f5a6b7c8d9e0f1
+              _userId:
+                type: string
+                format: objectId
+                readOnly: true
+                x-celigo-refModel: users
+                description: The end user's own user id.
+                examples:
+                  - 624774a6a7574d3ed9f9a5cc
+              email:
+                type:
+                  - string
+                  - 'null'
+                description: The end user's email. Null when the user record no longer resolves.
+              name:
+                type:
+                  - string
+                  - 'null'
+                description: The end user's display name. Null when unset or when the user record no longer resolves.
+              tools:
+                type: array
+                description: Tools the end user can invoke on this server.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: tools
+                      description: Tool id.
+                    name:
+                      type: string
+                      description: Tool name as exposed on this server.
+                    via:
+                      type: array
+                      description: |-
+                        Source attribution strings such as `direct`, `group:<name>`,
+                        `pset:<name> (group:<name>)`, `role-direct:<name>`, or
+                        `role:<name> (group:<name>)`.
+                      items:
+                        type: string
+    GrantCapability:
+      type: string
+      pattern: ^(?:tool|api):(?:[a-fA-F0-9]{24}|all)$|^pset:[a-fA-F0-9]{24}$
+      description: |-
+        Capability string granting access on this server: `tool:all`,
+        `tool:<24-char-hex-id>` (an IO tool `_toolId` or attached prompt `_id`),
+        `api:all`, `api:<24-char-hex-apiId>`, or
+        `pset:<24-char-hex-permissionSetId>` referencing a permission set defined
+        on this server.
+      examples:
+        - tool:all
+    BulkAssignEndUsersRequest:
+      type: object
+      description: |-
+        Bulk assignment payload. The same capabilities are applied to every
+        listed end user.
+      required:
+        - _ashareIds
+        - capabilities
+      properties:
+        _ashareIds:
+          type: array
+          minItems: 1
+          maxItems: 100
+          uniqueItems: true
+          description: |-
+            End-user access-record ids (from the end users list) to assign this
+            server's capabilities to. Every id must belong to an end user of this
+            account or the whole request is rejected before any update.
+          items:
+            type: string
+            format: objectId
+          examples:
+            - - 68b1c2d3e4f5a6b7c8d9e0f1
+              - 68b1c2d3e4f5a6b7c8d9e0f2
+        capabilities:
+          type: array
+          minItems: 1
+          description: |-
+            Capabilities to apply on this MCP server for every listed end user.
+            Each capability must resolve on this server — tools and APIs must be
+            attached to it and `pset:` ids must reference its permission sets.
+          items:
+            $ref: '#/components/schemas/GrantCapability'
+          examples:
+            - - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+    BulkAssignEndUsersResult:
+      type: object
+      description: |-
+        Result of a bulk end-user assignment. On a mid-batch failure the same
+        body is returned with a non-2xx status: `endUsers` holds the entries
+        processed before the failure and `errors` carries the error that stopped
+        the batch.
+      properties:
+        updated:
+          type: integer
+          description: |-
+            Number of end users processed, including end users whose grants
+            already matched and were left unchanged.
+          examples:
+            - 2
+        _mcpServerId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: mcpservers
+          description: MCP server the capabilities were assigned on.
+          examples:
+            - 69eb9fb5b4fc023618e490b8
+        serverName:
+          type:
+            - string
+            - 'null'
+          readOnly: true
+          description: Display name of the MCP server.
+          examples:
+            - Customer Integration MCP
+        endUsers:
+          type: array
+          description: Per-end-user assignment outcomes, in request order.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                description: End-user access-record id.
+                examples:
+                  - 68b1c2d3e4f5a6b7c8d9e0f1
+              _sharedWithUserId:
+                type: string
+                format: objectId
+                x-celigo-refModel: users
+                description: The end user's own user id.
+                examples:
+                  - 624774a6a7574d3ed9f9a5cc
+              resourceGrants:
+                type: array
+                description: |-
+                  The end user's complete resource grants after the merge. Only
+                  the grant for this server is replaced; grants for other MCP
+                  servers and wildcard grants are preserved.
+                items:
+                  type: object
+                  properties:
+                    resourceType:
+                      type: string
+                      enum:
+                        - mcpServer
+                      x-enumDescriptions:
+                        mcpServer: Grants access to an MCP server and its tools, APIs, or permission sets
+                      description: Resource type the grant applies to.
+                    _resourceId:
+                      type:
+                        - string
+                        - 'null'
+                      format: objectId
+                      x-celigo-refModel: mcpservers
+                      description: |-
+                        MCP server the grant applies to. Null for a wildcard grant
+                        across all MCP servers in the account.
+                    capabilities:
+                      type: array
+                      description: Capabilities granted on the target resource.
+                      items:
+                        type: string
+              capabilities:
+                type: array
+                description: Capabilities applied on this server for this end user.
+                items:
+                  type: string
+        errors:
+          type: array
+          description: |-
+            Present when the batch stopped early. Carries the first error
+            encountered; `endUsers` then reflects partial progress.
+          items:
+            type: object
+            properties:
+              code:
+                type: string
+                description: Machine-readable error code.
+              message:
+                type: string
+                description: Human-readable error message.
+    BulkAssignGroupsRequest:
+      type: object
+      description: |-
+        Bulk assignment payload. The same capabilities are applied to every
+        listed group.
+      required:
+        - _groupIds
+        - capabilities
+      properties:
+        _groupIds:
+          type: array
+          minItems: 1
+          maxItems: 100
+          uniqueItems: true
+          description: |-
+            Groups to assign this server's capabilities to. Every id must belong
+            to a group of this account or the whole request is rejected before
+            any update.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+          examples:
+            - - 68a1b2c3d4e5f6a7b8c9d0e1
+              - 68a1b2c3d4e5f6a7b8c9d0e2
+        capabilities:
+          type: array
+          minItems: 1
+          description: |-
+            Capabilities to apply on this MCP server for every listed group.
+            Each capability must resolve on this server — tools and APIs must be
+            attached to it and `pset:` ids must reference its permission sets.
+          items:
+            $ref: '#/components/schemas/GrantCapability'
+          examples:
+            - - pset:6a7b8c9d0e1f2a3b4c5d6e7f
+    BulkAssignGroupsResult:
+      type: object
+      description: |-
+        Result of a bulk group assignment. On a mid-batch failure the same body
+        is returned with a non-2xx status: `groups` holds the entries processed
+        before the failure and `errors` carries the error that stopped the batch.
+      properties:
+        updated:
+          type: integer
+          description: |-
+            Number of groups processed, including groups whose grants already
+            matched and were left unchanged.
+          examples:
+            - 2
+        _mcpServerId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: mcpservers
+          description: MCP server the capabilities were assigned on.
+          examples:
+            - 69eb9fb5b4fc023618e490b8
+        serverName:
+          type:
+            - string
+            - 'null'
+          readOnly: true
+          description: Display name of the MCP server.
+          examples:
+            - Customer Integration MCP
+        groups:
+          type: array
+          description: Per-group assignment outcomes, sorted by group name.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: groups
+                description: Group id.
+                examples:
+                  - 68a1b2c3d4e5f6a7b8c9d0e1
+              name:
+                type: string
+                description: Group name.
+                examples:
+                  - Finance
+              _roleIds:
+                type: array
+                description: Roles pinned to the group. Not changed by this operation.
+                items:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: roles
+              capabilities:
+                type: array
+                description: Capabilities applied on this server for this group.
+                items:
+                  type: string
+        errors:
+          type: array
+          description: |-
+            Present when the batch stopped early. Carries the first error
+            encountered; `groups` then reflects partial progress.
+          items:
+            type: object
+            properties:
+              code:
+                type: string
+                description: Machine-readable error code.
+              message:
+                type: string
+                description: Human-readable error message.
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+x-enable-proxy: true
+x-internal: false