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, optional upstream MCP servers proxied through mcp-type connections, and optional OAuth configuration. Tools support MCP annotations (read-only, idempotent, destructive, open-world) and per-server overrides for connections, exports, imports, and routing; a connection can be flagged so that each end user supplies their own credentials for it. Permission sets ("Capability Sets" in the UI) bundle a server's tools, APIs, prompts, and resources into named grants for end users, and the server-scoped access endpoints bulk-assign capabilities to end users and groups, report compiled effective access, and list the connections the server uses. Optional traffic limits (policies) — a server-level rate limit, a per-user rate limit, and a usage quota — reject calls over the limit with HTTP 429 and Retry-After before any tool runs, and an optional network policy restricts the IP ranges that may reach the server.
MCP server schema
Returns all MCP servers in the account.
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.
_integrationId,disabled,lastModifiedComma-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.
createdAt,lastModifiedMCP server list.
No MCP servers exist in the account.
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[].
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,
"connections": [
{
"_connectionId": "6ab1ebb94db5688fd8c7189f",
"requiresEndUserCredentials": true
}
],
"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": [],
"_promptIds": [],
"_resourceIds": []
}
],
"upstreamMcpConnections": [],
"policies": [],
"oauth": {
"useCeligoOauth": true
},
"createdAt": "2026-04-24T16:52:05.607Z",
"lastModified": "2026-05-07T15:22:16.985Z",
"enabledItemCount": 2
}
]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.
Request body for creating or updating an MCP server. On PUT, include the
full connections, tools, apis, prompts, resources,
permissionSets, and policies arrays because omitted arrays are
cleared; upstreamMcpConnections and _networkPolicyId are the
exceptions and keep their stored value when omitted. Every array entry
must be an object — a null entry in tools, apis, prompts,
resources, or upstreamMcpConnections is rejected with 422
mcp_server_invalid_array_item. Use PATCH to update individual fields
without affecting these arrays.
Display name for the MCP server.
Customer Integration MCPURI 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).
/customersPattern: ^\/[a-zA-Z0-9_\-]+$Description of the MCP server's purpose.
Exposes customer management tools for AI agent consumptionWhen true, the server refuses MCP clients. New servers start disabled.
Enabling requires at least one enabled tool, API, resource, or prompt,
or one enabled and available upstream capability — otherwise the write
is rejected with 422 mcp_server_enablement_requires_enabled_item.
trueNetwork policy whose IP allow and deny lists gate MCP protocol
requests to this server. Must reference a policy in the same
environment — any other id is rejected with 422 invalid_ref.
Preserved when omitted on PUT; send null (or PATCH remove) to
clear it, and deleting the policy with ?force=true clears it too.
Absent from responses when no policy is assigned.
6ab1ebbfb9e4547494ff7558Created MCP server.
MCP server object as returned by the API.
Display name for the MCP server.
Customer Integration MCPURI 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).
/customersPattern: ^\/[a-zA-Z0-9_\-]+$Description of the MCP server's purpose.
Exposes customer management tools for AI agent consumptionWhen true, the server refuses MCP clients. New servers start disabled.
Enabling requires at least one enabled tool, API, resource, or prompt,
or one enabled and available upstream capability — otherwise the write
is rejected with 422 mcp_server_enablement_requires_enabled_item.
trueNetwork policy whose IP allow and deny lists gate MCP protocol
requests to this server. Must reference a policy in the same
environment — any other id is rejected with 422 invalid_ref.
Preserved when omitted on PUT; send null (or PATCH remove) to
clear it, and deleting the policy with ?force=true clears it too.
Absent from responses when no policy is assigned.
6ab1ebbfb9e4547494ff7558Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZOwning user ID.
624cb0346309dc3a543733a2Marketplace template the server was installed from via
POST /v1/mcpservers/template/{_templateId}. Present only on
installed servers; a value sent on POST or PUT is ignored and the
field is not a PATCH path.
6ab129aeb9e4547494c0667fNumber of capabilities currently served — enabled tools, apis,
prompts, and resources plus every enabled and available upstream
tool, prompt, and resource row. Computed on GET and list responses
only (it is absent from create and update responses) and reported
even when include omits the arrays it counts.
5When true, the server is an unconfirmed draft created by the
AI-assisted builder. Present, together with draftExpiresAt, only
on such drafts.
trueTimestamp when this draft MCP server expires and is automatically
deleted. Present only on unconfirmed drafts, alongside draft.
2026-05-14T17:16:05.595ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
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,
"connections": [],
"tools": [],
"apis": [],
"resources": [],
"prompts": [],
"permissionSets": [],
"upstreamMcpConnections": [],
"policies": [],
"createdAt": "2026-04-24T16:52:05.607Z",
"lastModified": "2026-04-24T16:52:05.607Z"
}Returns the full configuration of an MCP server including tools, APIs, prompts, resources, connections, upstream MCP connections, and OAuth settings. Each upstream connection row is enriched with the connection's current name and each upstream capability with its effective title, annotations, and (when overridden) name; enabledItemCount is computed on this response and the list response only.
MCP server ID.
69eb9fb5b4fc023618e490b8MCP server configuration.
MCP server object as returned by the API.
Display name for the MCP server.
Customer Integration MCPURI 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).
/customersPattern: ^\/[a-zA-Z0-9_\-]+$Description of the MCP server's purpose.
Exposes customer management tools for AI agent consumptionWhen true, the server refuses MCP clients. New servers start disabled.
Enabling requires at least one enabled tool, API, resource, or prompt,
or one enabled and available upstream capability — otherwise the write
is rejected with 422 mcp_server_enablement_requires_enabled_item.
trueNetwork policy whose IP allow and deny lists gate MCP protocol
requests to this server. Must reference a policy in the same
environment — any other id is rejected with 422 invalid_ref.
Preserved when omitted on PUT; send null (or PATCH remove) to
clear it, and deleting the policy with ?force=true clears it too.
Absent from responses when no policy is assigned.
6ab1ebbfb9e4547494ff7558Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZOwning user ID.
624cb0346309dc3a543733a2Marketplace template the server was installed from via
POST /v1/mcpservers/template/{_templateId}. Present only on
installed servers; a value sent on POST or PUT is ignored and the
field is not a PATCH path.
6ab129aeb9e4547494c0667fNumber of capabilities currently served — enabled tools, apis,
prompts, and resources plus every enabled and available upstream
tool, prompt, and resource row. Computed on GET and list responses
only (it is absent from create and update responses) and reported
even when include omits the arrays it counts.
5When true, the server is an unconfirmed draft created by the
AI-assisted builder. Present, together with draftExpiresAt, only
on such drafts.
trueTimestamp when this draft MCP server expires and is automatically
deleted. Present only on unconfirmed drafts, alongside draft.
2026-05-14T17:16:05.595ZUnauthorized. 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[].
Not found. The requested resource does not exist or is not visible to the caller.
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,
"connections": [
{
"_connectionId": "6ab1ebb94db5688fd8c7189f",
"requiresEndUserCredentials": true
}
],
"tools": [
{
"_toolId": "69d462d5b9c28ea0b7f82522",
"name": "get_customer",
"disabled": false,
"annotations": {
"readOnlyHint": true
},
"overrides": {
"connections": [
{
"_abstractId": "6ab1ebb94db5688fd8c7189f",
"_id": "6ab1ebb94db5688fd8c7189f",
"requiresEndUserCredentials": 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": [],
"_promptIds": [],
"_resourceIds": []
}
],
"upstreamMcpConnections": [
{
"_connectionId": "6a6655fce52f3c30d0a53926",
"alias": "deepwiki",
"name": "DeepWiki MCP",
"discoveryStatus": "ok",
"lastDiscoveredAt": "2026-09-22T02:53:01.591Z",
"tools": [
{
"_id": "6ab1ebd05af4c5a3ea6b0959",
"upstreamName": "read_wiki_structure",
"disabled": false,
"approvedDefinitionHash": "8b2c61f30b7ccf6fd57e53acc0c4bceee11fa8192ec586631c9fe6cd702fdfd0",
"changedSinceApproval": false,
"unavailable": false,
"title": "read_wiki_structure",
"description": "Get a list of documentation topics for a GitHub repository.",
"annotations": {}
},
{
"_id": "6ab1ebd05af4c5a3ea6b095a",
"upstreamName": "ask_wiki_question",
"disabled": false,
"overrides": {
"name": "ask_about_repo"
},
"approvedDefinitionHash": "3afbdaf02826766eb5e7634b45974d38ea1e917875210ebae2201c8d42302eaf",
"changedSinceApproval": false,
"unavailable": false,
"title": "ask_wiki_question",
"name": "ask_about_repo",
"description": "Ask a question about a public GitHub repository's codebase.",
"annotations": {}
}
],
"prompts": [],
"resources": []
}
],
"_networkPolicyId": "6ab1ebbfb9e4547494ff7558",
"policies": [],
"oauth": {
"useCeligoOauth": true
},
"createdAt": "2026-04-24T16:52:05.607Z",
"lastModified": "2026-05-07T15:22:16.985Z",
"enabledItemCount": 4
}Full replacement of an MCP server's configuration. Omitted arrays (connections, tools, apis, prompts, resources, permissionSets, policies) are cleared, so include the complete arrays — clearing permissionSets this way also rewrites the pset: grants that referenced the erased sets, clearing policies removes every traffic limit, and — by the platform contract — dropping a connection that required end-user credentials invalidates the end users' mcpChild connections for it unless another server still requires them. Two fields work the other way round: upstreamMcpConnections and _networkPolicyId keep their stored value when omitted — send [] or null respectively to clear them — and a PUT that includes upstreamMcpConnections re-approves the current upstream definitions. _templateId is ignored. relativeURI can be changed but must remain unique per account.
MCP server ID.
69eb9fb5b4fc023618e490b8Request body for creating or updating an MCP server. On PUT, include the
full connections, tools, apis, prompts, resources,
permissionSets, and policies arrays because omitted arrays are
cleared; upstreamMcpConnections and _networkPolicyId are the
exceptions and keep their stored value when omitted. Every array entry
must be an object — a null entry in tools, apis, prompts,
resources, or upstreamMcpConnections is rejected with 422
mcp_server_invalid_array_item. Use PATCH to update individual fields
without affecting these arrays.
Display name for the MCP server.
Customer Integration MCPURI 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).
/customersPattern: ^\/[a-zA-Z0-9_\-]+$Description of the MCP server's purpose.
Exposes customer management tools for AI agent consumptionWhen true, the server refuses MCP clients. New servers start disabled.
Enabling requires at least one enabled tool, API, resource, or prompt,
or one enabled and available upstream capability — otherwise the write
is rejected with 422 mcp_server_enablement_requires_enabled_item.
trueNetwork policy whose IP allow and deny lists gate MCP protocol
requests to this server. Must reference a policy in the same
environment — any other id is rejected with 422 invalid_ref.
Preserved when omitted on PUT; send null (or PATCH remove) to
clear it, and deleting the policy with ?force=true clears it too.
Absent from responses when no policy is assigned.
6ab1ebbfb9e4547494ff7558Updated MCP server.
MCP server object as returned by the API.
Display name for the MCP server.
Customer Integration MCPURI 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).
/customersPattern: ^\/[a-zA-Z0-9_\-]+$Description of the MCP server's purpose.
Exposes customer management tools for AI agent consumptionWhen true, the server refuses MCP clients. New servers start disabled.
Enabling requires at least one enabled tool, API, resource, or prompt,
or one enabled and available upstream capability — otherwise the write
is rejected with 422 mcp_server_enablement_requires_enabled_item.
trueNetwork policy whose IP allow and deny lists gate MCP protocol
requests to this server. Must reference a policy in the same
environment — any other id is rejected with 422 invalid_ref.
Preserved when omitted on PUT; send null (or PATCH remove) to
clear it, and deleting the policy with ?force=true clears it too.
Absent from responses when no policy is assigned.
6ab1ebbfb9e4547494ff7558Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZOwning user ID.
624cb0346309dc3a543733a2Marketplace template the server was installed from via
POST /v1/mcpservers/template/{_templateId}. Present only on
installed servers; a value sent on POST or PUT is ignored and the
field is not a PATCH path.
6ab129aeb9e4547494c0667fNumber of capabilities currently served — enabled tools, apis,
prompts, and resources plus every enabled and available upstream
tool, prompt, and resource row. Computed on GET and list responses
only (it is absent from create and update responses) and reported
even when include omits the arrays it counts.
5When true, the server is an unconfirmed draft created by the
AI-assisted builder. Present, together with draftExpiresAt, only
on such drafts.
trueTimestamp when this draft MCP server expires and is automatically
deleted. Present only on unconfirmed drafts, alongside draft.
2026-05-14T17:16:05.595ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
PUT /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 803
{
"name": "Customer Integration MCP",
"relativeURI": "/customers",
"description": "Exposes customer management tools for AI agent consumption",
"disabled": false,
"connections": [
{
"_connectionId": "6ab1ebb94db5688fd8c7189f",
"requiresEndUserCredentials": true
}
],
"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,
"connections": [
{
"_connectionId": "6ab1ebb94db5688fd8c7189f",
"requiresEndUserCredentials": true
}
],
"tools": [
{
"_toolId": "69d462d5b9c28ea0b7f82522",
"name": "get_customer",
"disabled": false,
"annotations": {
"readOnlyHint": true
}
}
],
"apis": [
{
"name": "order_lookup",
"_apiId": "68ae4264b5f755d2dd3796b4",
"disabled": false
}
],
"resources": [
{
"_id": "6aa970882c7f7fbf96a81c5e",
"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": [],
"_promptIds": [],
"_resourceIds": []
}
],
"upstreamMcpConnections": [],
"policies": [],
"oauth": {
"useCeligoOauth": true
},
"createdAt": "2026-04-24T16:52:05.607Z",
"lastModified": "2026-05-07T15:22:16.985Z"
}Soft-deletes an MCP server. Retained in the recycle bin for 30 days before permanent removal.
MCP server ID.
69eb9fb5b4fc023618e490b8Deleted.
No content
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[].
Not found. The requested resource does not exist or is not visible to the caller.
DELETE /v1/mcpservers/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Partially updates an MCP server using a JSON Patch document (RFC 6902). The whitelisted paths are /name, /disabled, /policies, /_networkPolicyId, and /upstreamMcpConnections/{index}/alias — every other path, including the whole /upstreamMcpConnections array and any nested upstream row, is rejected with 422 not a whitelisted property. Under /policies, add, replace, and remove work on the whole array, add works at /policies/- or an index, and replace works at an index or a sub-path such as /policies/0/config/limit; remove at an array index is rejected with 422 Remove at array index is not supported. The resulting array is validated as a whole, and a policy with invalid config (422 policy_config_invalid), a missing name, or a second policy of the same type and keyResolver (422 mcp_server_duplicate_policy) rejects the entire patch. /_networkPolicyId takes add, replace (a policy in the same environment, else 422 invalid_ref), and remove to unassign — replace with a null value is rejected with 422 missing 'value' property. Setting /disabled to false is rejected with 422 mcp_server_enablement_requires_enabled_item unless at least one tool, API, prompt, resource, or available upstream row is enabled.
MCP server ID.
69eb9fb5b4fc023618e490b8A JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.
The operation to perform.
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".
The new value to set. Required for replace and add, omit for remove.
Patch applied.
No content
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[].
Not found. The requested resource does not exist or is not visible to the caller.
The patch names a path outside the whitelist, an invalid
_networkPolicyId, an invalid policy, or would enable a server with
nothing enabled.
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
Installs a published MCP-server marketplace template (a template whose type is mcpserver). The request takes no parameters — the published template ZIP is the source of truth for everything the install creates, and there is no connectionMap (unlike the integration-template install).
What the install creates depends on the template's contents, reported by the response's destination envelope:
Prompt-only templates (no tools) create the MCP server immediately, disabled.
destination.resourceTypeismcpservers.Tool-bearing templates hand off to the Integration installer:
destination.resourceTypeisintegrationsand names an Integration in install mode, where connection mapping and the remaining install steps continue. The MCP server is created — disabled — by the Integration's terminal install step, after the tools are cloned.
Integration templates do not install through this path — they use POST /v1/integrations/template/{_id}. Each path rejects the other class: this one returns 404 for a template that is not a published MCP-server template, and the integration path rejects MCP-server templates with a 400 invalid_template error.
Every request that reaches the platform starts a new install — there is no idempotency key, so retrying after a timeout or ambiguous failure creates a duplicate server or install-mode Integration. Duplicates are kept apart by URI suffixing: each new server's relativeURI gets -2 through -100 appended when the un-suffixed value is taken; once all 100 are in use the install fails with a 422 invalid_value error.
Requires the install:published:template permission.
The published MCP-server template to install.
6ab129aeb9e4547494c0667fEmpty object — the install takes no parameters.
Installation started.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
No published MCP-server template with this ID. Integration templates
return 404 here too — they install via
POST /v1/integrations/template/{_id}.
The install was rejected before anything was created. As-built
cases: the template packages capabilities an MCP-server template
cannot carry (invalid_template — only tools and inline prompts
are portable), a packaged tool is missing or inaccessible
(invalid_template), or relativeURI de-duplication exhausted its
-2…-100 suffixes (invalid_value — the account already holds
100 servers on that URI; delete or rename some before installing
again). None of these are retryable unchanged — and never retry
the POST blindly, since a request that reached the platform may
already have installed something.
POST /v1/mcpservers/template/{_templateId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2
{}{
"destination": {
"resourceType": "integrations",
"resourceId": "6ab130000000000000000d01"
}
}Generates a template ZIP from the MCP server and returns a temporary signed URL for downloading it. The ZIP contains the server document, its inline prompts, its tools, and the resources those tools depend on (exports, imports, connections, scripts) — a prompt-only server (no tools) exports successfully. The ZIP is the artifact a publisher uploads when authoring an MCP-server marketplace template; installing that template recreates the server via POST /v1/mcpservers/template/{_templateId}.
Only tools and inline prompts are portable. A server that publishes APIs (apis[]) or file resources (resources[]) fails the export up front with a 400 invalid_template error — no ZIP is generated; nothing is stripped to make it succeed.
The signed URL expires after about 60 seconds — download promptly, and call the endpoint again for a fresh URL rather than storing this one.
Requires the create:mcpserver:template permission.
The MCP server to export.
69eb9fb5b4fc023618e490b8Temporary signed URL for the generated ZIP.
Time-limited download URL for the generated template ZIP — expires after about 60 seconds.
Storage key of the generated ZIP object — stable across the URL's expiry, useful for correlating repeated exports.
The server publishes capabilities a template cannot carry — only tools and inline prompts are portable. Remove the APIs / file resources (or export a server without them); retrying unchanged fails identically.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
The export could not assemble a complete ZIP — a tool or its backing integration is missing or not accessible to the caller.
GET /v1/mcpservers/{_id}/template HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"signedURL": "https://s3.amazonaws.com/templates/mcp-export/69eb9fb5b4fc023618e490b8.zip?X-Amz-Expires=60",
"key": "mcp-export/69eb9fb5b4fc023618e490b8.zip"
}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.
Resource ID.
Dependency map. Keys are resource-type strings; values are arrays
of dependency entries. Returns {} when no dependents exist.
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.
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[].
GET /v1/mcpservers/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Server-scoped reverse lookup: finds every end user who can reach this MCP server and compiles each one's effective access — tools, APIs, prompts, and file resources — 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. The account owner is never listed — owners have MCP access without an end-user record, so there is no record to compile — and an empty result therefore means no end user has been granted this server. Requires account owner or administrator access. The per-user view of the same compilation is GET /v1/endusers/{_ashareId}/effective-access (End Users API).
MCP server ID.
69eb9fb5b4fc023618e490b8Compiled effective access by end user.
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.
MCP server this compilation applies to.
69eb9fb5b4fc023618e490b8Display name of the MCP server.
Customer Integration MCPBad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
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": "jane.doe@example.com",
"name": "Jane Doe",
"tools": [
{
"_id": "69d462d5b9c28ea0b7f82522",
"name": "get_customer",
"via": [
"pset:Finance read-only (group:Finance)"
]
}
],
"apis": [],
"prompts": [
{
"_id": "6b2c3d4e5f6a7b8c9d0e1f2a",
"name": "summarize_meeting",
"via": [
"direct"
]
}
],
"resources": []
}
]
}Returns the connections attached to the server as full Connection documents, sorted by name. By default these are the parents — every connection named in connections[] or in a tool's overrides.connections[], whether or not it requires end-user credentials (connections reached only through overrides.exports[] or overrides.imports[] are not included). With connectionRole=mcpChild it returns instead the mcpChild connections end users hold against those parents — the only route that serves a child document, since GET /v1/connections never lists one and GET /v1/connections/{_id} answers 404 for one. On a child, _userId is the end user who owns it and _mcpOwnerId is the account; credentials are masked as on every connection read. There is no row for an end user who has not connected yet — derive that by joining the child rows' _userId against GET /v1/mcpservers/{_id}/effective-access. A malformed _id is rejected with 400 invalid_ref ("Please provide a valid _id."); an unknown one with 404. Requires account owner or administrator access.
MCP server ID.
69eb9fb5b4fc023618e490b8Which side of the end-user credential relationship to list. Omit it
(or send standard) for the parents the server attaches; send
mcpChild for the end users' child connections against them.
mcpChildPossible values: Maximum number of connections to return per page.
100Field to order the page by; the default orders by name.
lastModifiedPossible values: Opaque cursor for forward pagination. Pass the value from the Link
response header (rel="next") to fetch the next page.
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.
_integrationId,disabled,lastModifiedComma-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.
createdAt,lastModifiedConnection documents matching the requested role, sorted by name.
No connection matches the requested role on this server.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
MCP server not found in this account.
limit is not a positive integer (invalid_query_param), or
include and exclude were both sent (invalid_query_params).
GET /v1/mcpservers/{_id}/connections HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "6ab1ebb94db5688fd8c7189f",
"name": "Partner order API",
"type": "http",
"connectionRole": "standard",
"endUserProvidedFields": [
"http.auth.token.token"
],
"http": {
"formType": "http",
"mediaType": "json",
"baseURI": "https://api.partner.example.com"
},
"createdAt": "2026-09-22T02:45:13.984Z",
"lastModified": "2026-09-22T02:45:14.550Z"
}
]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.
MCP server ID.
69eb9fb5b4fc023618e490b8Bulk assignment payload. The same capabilities are applied to every listed end user.
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.
["68b1c2d3e4f5a6b7c8d9e0f1","68b1c2d3e4f5a6b7c8d9e0f2"]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.
["pset:6a7b8c9d0e1f2a3b4c5d6e7f"]All end users processed.
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.
Number of end users processed, including end users whose grants already matched and were left unchanged.
2MCP server the capabilities were assigned on.
69eb9fb5b4fc023618e490b8Display name of the MCP server.
Customer Integration MCPValidation 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.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
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).
A duplicate end-user share was detected while persisting mid-batch
(enduser_ashare_exists). Returns the result body with partial
progress plus errors.
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"
]
}
]
}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.
MCP server ID.
69eb9fb5b4fc023618e490b8Bulk assignment payload. The same capabilities are applied to every listed group.
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.
["68a1b2c3d4e5f6a7b8c9d0e1","68a1b2c3d4e5f6a7b8c9d0e2"]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.
["pset:6a7b8c9d0e1f2a3b4c5d6e7f"]All groups processed. groups is sorted by group name.
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.
Number of groups processed, including groups whose grants already matched and were left unchanged.
2MCP server the capabilities were assigned on.
69eb9fb5b4fc023618e490b8Display name of the MCP server.
Customer Integration MCPValidation 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.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
MCP server not found in this account.
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"
]
}
]
}Last updated
Was this helpful?