MCP Servers

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

List MCP servers

get

/v1/mcpservers

Returns all MCP servers in the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includestringOptional

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.

Example: _integrationId,disabled,lastModified

excludestringOptional

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.

Example: createdAt,lastModified

Responses

200

MCP server list.

application/json

204

No MCP servers exist in the account.

401

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[].

application/json

get/v1/mcpservers

GET /v1/mcpservers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_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"
  }
]

Create an MCP server

post

/v1/mcpservers

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

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.

namestring · min: 1 · max: 150Required

Display name for the MCP server.

Example: Customer Integration MCP

relativeURIstring · max: 131072Required

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).

Example: /customersPattern: ^\/[a-zA-Z0-9_\-]+$

descriptionstring · max: 1000Optional

Description of the MCP server's purpose.

Example: Exposes customer management tools for AI agent consumption

disabledbooleanOptional

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.

Default: true

Responses

201

Created MCP server.

application/json

MCP server object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the MCP server.

Example: Customer Integration MCP

relativeURIstring · max: 131072Required

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).

Example: /customersPattern: ^\/[a-zA-Z0-9_\-]+$

descriptionstring · max: 1000Optional

Description of the MCP server's purpose.

Example: Exposes customer management tools for AI agent consumption

disabledbooleanRequired

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.

Default: true

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

draftExpiresAtstring · date-timeRead-onlyOptional

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.

Example: 2026-05-14T17:16:05.595Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

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[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/mcpservers

POST /v1/mcpservers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "name": "Customer Integration MCP",
  "relativeURI": "/customers"
}

{
  "_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"
}

Get an MCP server

get

/v1/mcpservers/{_id}

Returns the full configuration of an MCP server including tools, APIs, prompts, resources, and OAuth settings.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Responses

200

MCP server configuration.

application/json

MCP server object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the MCP server.

Example: Customer Integration MCP

relativeURIstring · max: 131072Required

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).

Example: /customersPattern: ^\/[a-zA-Z0-9_\-]+$

descriptionstring · max: 1000Optional

Description of the MCP server's purpose.

Example: Exposes customer management tools for AI agent consumption

disabledbooleanRequired

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.

Default: true

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

draftExpiresAtstring · date-timeRead-onlyOptional

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.

Example: 2026-05-14T17:16:05.595Z

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/mcpservers/{_id}

GET /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_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"
}

Update an MCP server

put

/v1/mcpservers/{_id}

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Body

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.

namestring · min: 1 · max: 150Required

Display name for the MCP server.

Example: Customer Integration MCP

relativeURIstring · max: 131072Required

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).

Example: /customersPattern: ^\/[a-zA-Z0-9_\-]+$

descriptionstring · max: 1000Optional

Description of the MCP server's purpose.

Example: Exposes customer management tools for AI agent consumption

disabledbooleanOptional

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.

Default: true

Responses

200

Updated MCP server.

application/json

MCP server object as returned by the API.

namestring · min: 1 · max: 150Required

Display name for the MCP server.

Example: Customer Integration MCP

relativeURIstring · max: 131072Required

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).

Example: /customersPattern: ^\/[a-zA-Z0-9_\-]+$

descriptionstring · max: 1000Optional

Description of the MCP server's purpose.

Example: Exposes customer management tools for AI agent consumption

disabledbooleanRequired

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.

Default: true

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyOptional

Owning user ID.

Example: 624cb0346309dc3a543733a2

draftExpiresAtstring · date-timeRead-onlyOptional

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.

Example: 2026-05-14T17:16:05.595Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/mcpservers/{_id}

PUT /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 708

{
  "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
  }
}

{
  "_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"
}

Delete an MCP server

delete

/v1/mcpservers/{_id}

Soft-deletes an MCP server. Retained in the recycle bin for 30 days before permanent removal.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Responses

204

Deleted.

No content

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/mcpservers/{_id}

DELETE /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch an MCP server

patch

/v1/mcpservers/{_id}

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Bodyobject · JsonPatchOperation[]

A JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.

opstring · enumRequired

The operation to perform.

Possible values:

pathstringRequired

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".

valueanyOptional

The new value to set. Required for replace and add, omit for remove.

Responses

204

Patch applied.

No content

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

patch/v1/mcpservers/{_id}

PATCH /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50

[
  {
    "op": "replace",
    "path": "/disabled",
    "value": true
  }
]

No content

List dependencies of an MCP server

get

/v1/mcpservers/{_id}/dependencies

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Resource ID.

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

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.

401

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[].

application/json

get/v1/mcpservers/{_id}/dependencies

GET /v1/mcpservers/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}

Get effective end-user access for an MCP server

get

/v1/mcpservers/{_id}/effective-access

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).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Responses

200

Compiled effective access by end user.

application/json

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.

_mcpServerIdstring · objectIdRead-onlyOptional

MCP server this compilation applies to.

Example: 69eb9fb5b4fc023618e490b8

serverNamestring · nullableRead-onlyOptional

Display name of the MCP server.

Example: Customer Integration MCP

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

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[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/mcpservers/{_id}/effective-access

GET /v1/mcpservers/{_id}/effective-access HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_mcpServerId": "69eb9fb5b4fc023618e490b8",
  "serverName": "Customer Integration MCP",
  "users": [
    {
      "_ashareId": "68b1c2d3e4f5a6b7c8d9e0f1",
      "_userId": "624774a6a7574d3ed9f9a5cc",
      "email": "[e-mail]",
      "name": "Jane Doe",
      "tools": [
        {
          "_id": "69d462d5b9c28ea0b7f82522",
          "name": "get_customer",
          "via": [
            "pset:Finance read-only (group:Finance)"
          ]
        }
      ]
    }
  ]
}

Bulk assign MCP server access to end users

put

/v1/mcpservers/{_id}/endusers

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Body

Bulk assignment payload. The same capabilities are applied to every listed end user.

_ashareIdsstring · objectId[] · min: 1 · max: 100Required

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.

Example: ["68b1c2d3e4f5a6b7c8d9e0f1","68b1c2d3e4f5a6b7c8d9e0f2"]

capabilitiesstring[] · min: 1Required

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.

Example: ["pset:6a7b8c9d0e1f2a3b4c5d6e7f"]

Responses

200

All end users processed.

application/json

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.

updatedintegerOptional

Number of end users processed, including end users whose grants already matched and were left unchanged.

Example: 2

_mcpServerIdstring · objectIdRead-onlyOptional

MCP server the capabilities were assigned on.

Example: 69eb9fb5b4fc023618e490b8

serverNamestring · nullableRead-onlyOptional

Display name of the MCP server.

Example: Customer Integration MCP

400

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.

application/json

401

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[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

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).

application/json

409

A duplicate end-user share was detected while persisting mid-batch (enduser_ashare_exists). Returns the result body with partial progress plus errors.

application/json

put/v1/mcpservers/{_id}/endusers

PUT /v1/mcpservers/{_id}/endusers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "_ashareIds": [
    "68b1c2d3e4f5a6b7c8d9e0f1",
    "68b1c2d3e4f5a6b7c8d9e0f2"
  ],
  "capabilities": [
    "pset:6a7b8c9d0e1f2a3b4c5d6e7f"
  ]
}

{
  "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"
      ]
    }
  ]
}

Bulk assign MCP server access to groups

put

/v1/mcpservers/{_id}/groups

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

MCP server ID.

Example: 69eb9fb5b4fc023618e490b8

Body

Bulk assignment payload. The same capabilities are applied to every listed group.

_groupIdsstring · objectId[] · min: 1 · max: 100Required

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.

Example: ["68a1b2c3d4e5f6a7b8c9d0e1","68a1b2c3d4e5f6a7b8c9d0e2"]

capabilitiesstring[] · min: 1Required

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.

Example: ["pset:6a7b8c9d0e1f2a3b4c5d6e7f"]

Responses

200

All groups processed. groups is sorted by group name.

application/json

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.

updatedintegerOptional

Number of groups processed, including groups whose grants already matched and were left unchanged.

Example: 2

_mcpServerIdstring · objectIdRead-onlyOptional

MCP server the capabilities were assigned on.

Example: 69eb9fb5b4fc023618e490b8

serverNamestring · nullableRead-onlyOptional

Display name of the MCP server.

Example: Customer Integration MCP

400

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.

application/json

401

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[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

MCP server not found in this account.

application/json

put/v1/mcpservers/{_id}/groups

PUT /v1/mcpservers/{_id}/groups HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "_groupIds": [
    "68a1b2c3d4e5f6a7b8c9d0e1",
    "68a1b2c3d4e5f6a7b8c9d0e2"
  ],
  "capabilities": [
    "pset:6a7b8c9d0e1f2a3b4c5d6e7f"
  ]
}

{
  "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"
      ]
    }
  ]
}