# MCP Servers

## List MCP servers

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

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"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.\nTriggers **summary projection** on supported list endpoints: the server\nreturns a minimal identity set for each record (`_id`, `name`, plus a\nresource-specific always-on set like `adaptorType` on exports/imports,\nor richer defaults on `ashares`, `audit`, `httpconnectors`, `transfers`,\netc.) and adds any listed fields that exist on the record. Listed fields\nthe record doesn't carry are silently dropped.\n\nDot notation is supported for projecting nested sub-fields — e.g.\n`include=ftp.directoryPath` on `/v1/exports` returns just that nested\nfield inside `ftp` for FTP-type exports (and omits `ftp` entirely for\nnon-FTP exports).\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n  comma separator; digits are also accepted in practice. Any other\n  character returns **400 `invalid_query_params`**.\n- Empty value (`include=`) or bare `include` is ignored — the full\n  default record is returned.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n  returns **400 `invalid_query_params`**: *\"Please provide either\n  include or exclude param in the request query and not both.\"*\n- Array-bracket syntax (`include[]=...`) is not supported and can return\n  a 500.\n- Only list endpoints honor projection — on GET-by-id the parameter is\n  silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n  `exclude` with **400 `invalid_query_params`** and a message of the form\n  *\"Include or exclude query params are not applicable for `<resource>`\n  resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n  `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to remove from the default response on\nsupported list endpoints. Unlike `include`, `exclude` does NOT trigger\nsummary projection — callers get the standard full-record shape with the\nnamed fields stripped out.\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n  comma separator; digits are also accepted in practice. Any other\n  character returns **400 `invalid_query_params`**.\n- Empty value (`exclude=`) is ignored.\n- Certain protected identity fields **cannot be stripped** — e.g.\n  `exclude=name` on `/v1/exports` is silently ignored and `name` remains\n  in the response. Protected sets vary per resource.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n  returns **400 `invalid_query_params`**: *\"Please provide either\n  include or exclude param in the request query and not both.\"*\n- Only list endpoints honor stripping — on GET-by-id the parameter is\n  silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n  `exclude` with **400 `invalid_query_params`** and a message of the form\n  *\"Include or exclude query params are not applicable for `<resource>`\n  resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n  `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}}},"schemas":{"Response":{"type":"object","description":"Response schema for MCP server operations.\n\nContains the complete MCP server configuration including metadata,\ntool entries, API entries, and their override settings.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the MCP server"},"_userId":{"type":"string","format":"objectId","readOnly":true,"description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the MCP server"},"relativeURI":{"type":"string","description":"URI path segment for the MCP server endpoint"},"description":{"type":"string","description":"Description of the MCP server's purpose"},"disabled":{"type":"boolean","description":"Whether the MCP server is disabled"},"tools":{"type":"array","description":"Tool entries referencing Celigo Tool resources","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries referencing Celigo builder-mode API resources","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Always\npresent in responses — servers with no prompts configured return\n`prompts: []`.","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"description":"OAuth 2.0 configuration. Always present in responses — servers\nwithout OAuth configured still return `oauth: {useIntrospection: false}`.","allOf":[{"$ref":"#/components/schemas/OAuthConfig"}]},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was soft-deleted.\n\nOnly present for deleted servers. The server will be permanently\nremoved 30 days after this timestamp.\n"}}},"IOTool":{"type":"object","description":"A tool entry within an MCP server that references a Tool resource.\n\nEach IO tool maps a Celigo Tool to an MCP-compatible tool endpoint. The tool's\ninput schema must have `type: \"object\"` to comply with the MCP specification.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"_toolId":{"type":"string","format":"objectId","description":"Reference to the Tool resource that this MCP tool exposes.\n\nThe referenced tool must exist, belong to the same user, and have an\ninput schema with `type: \"object\"`.\n"},"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this tool is disabled within the MCP server.\n\nDisabled tools are not exposed to MCP clients. At least one tool or API\nmust be enabled for the server itself to be enabled.\n"},"annotations":{"$ref":"#/components/schemas/Annotations"},"overrides":{"$ref":"#/components/schemas/Overrides"}},"required":["_toolId","name"]},"Annotations":{"type":"object","description":"MCP-standard annotations that hint at the behavior of a tool.\n\nThese annotations follow the Model Context Protocol specification and help\nAI agents and MCP clients understand how a tool behaves without executing it.\nAll fields are optional hints — they are not enforced by the server.\n","properties":{"title":{"type":"string","maxLength":300,"description":"Human-readable title for the tool, displayed in MCP client UIs.\n\nIf not provided, the tool's `name` field is used instead.\n"},"destructiveHint":{"type":"boolean","description":"Hints that the tool may perform destructive operations such as\ndeleting or permanently modifying data.\n"},"idempotentHint":{"type":"boolean","description":"Hints that calling the tool multiple times with the same input\nproduces the same result without additional side effects.\n"},"openWorldHint":{"type":"boolean","description":"Hints that the tool interacts with an open-world environment\n(e.g., external APIs) where results may vary between calls.\n"},"readOnlyHint":{"type":"boolean","description":"Hints that the tool only reads data and does not modify any state.\n"}}},"Overrides":{"type":"object","description":"Per-server overrides for a tool's internal resources.\n\nWhen a tool is added to an MCP server, its connections, exports, imports,\nand routers can be customized for this specific server context without\nmodifying the underlying tool definition. This enables reusing the same\ntool across multiple MCP servers with different configurations.\n","properties":{"connections":{"type":"array","description":"Connection overrides. Each entry maps an abstract connection reference\nin the tool to a concrete connection resource for this server.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"The abstract connection identifier from the tool definition.\nThis is the connection reference that will be replaced.\n"},"_id":{"type":"string","format":"objectId","description":"The concrete connection resource to use in place of the abstract reference.\n"},"_borrowConcurrencyFromConnectionId":{"type":"string","description":"Optional connection from which to borrow concurrency limits.\n"}},"required":["_abstractId"]}},"exports":{"type":"array","description":"Export (lookup) overrides. Customize export resources used within the tool,\nincluding connection bindings, scheduling, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract export identifier from the tool definition"},"_id":{"type":"string","format":"objectId","description":"Concrete export resource to use"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this export"},"type":{"type":"string","enum":["webhook","distributed","test","delta","once","tranlinedelta","simple","blob","all"],"description":"Override the export type"},"pageSize":{"type":"number","description":"Override the page size for pagination"},"skipRetries":{"type":"boolean","description":"Whether to skip retries on failure"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}}},"required":["_abstractId"]}},"imports":{"type":"array","description":"Import overrides. Customize import resources used within the tool,\nincluding connection bindings, hooks, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract import identifier from the tool definition"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this import"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}},"hooks":{"type":"object","description":"Override script hooks","properties":{"preMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}},"postMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}}}}},"required":["_abstractId"]}},"routers":{"type":"array","description":"Router overrides. Customize routing behavior for specific branches\nwithin the tool, including branch filters and routing strategies.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract router identifier from the tool definition"},"name":{"type":"string","description":"Override the router name"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch","all_matching_branches"],"description":"Override the routing strategy"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Override the routing evaluation method"},"script":{"type":"object","description":"Override the router script","properties":{"_scriptId":{"type":"string","format":"objectId"},"function":{"type":"string"}}},"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"},"description":{"type":"string","description":"Override the branch description"},"inputFilter":{"type":"object","description":"Override the branch filter criteria","properties":{"version":{"type":"string","enum":["1"]},"rules":{"type":"array","items":{}}}}}}}},"required":["_abstractId"]}}}},"ApiTool":{"type":"object","description":"An API entry within an MCP server that references a builder-mode API resource.\n\nEach API tool maps a Celigo API to an MCP-compatible tool endpoint. Only\nbuilder-type APIs (not script-type) can be used in MCP servers.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"_apiId":{"type":"string","format":"objectId","description":"Reference to the API resource that this MCP tool exposes.\n\nThe referenced API must exist, belong to the same user, and be of\ntype \"builder\" (script-type APIs are not supported).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this API tool is disabled within the MCP server.\n\nDisabled API tools are not exposed to MCP clients.\n"}},"required":["name","_apiId"]},"Prompt":{"type":"object","description":"A prompt template exposed to MCP clients by this server.\n\nMCP prompts are named templates that clients can request with a set of\narguments; the server substitutes the arguments into `messagesTemplate`\nand returns the resulting message list. Prompt names must be unique\nacross all prompts on the server.\n","properties":{"name":{"type":"string","description":"Prompt identifier exposed to MCP clients. Used by clients to request\nthis prompt via `prompts/get`.\n\nMust be unique within the server's `prompts[]`. Duplicates return\n422 `mcp_server_duplicate_prompt_name` on `prompts.<index>.name`."},"title":{"type":"string","description":"Short human-readable title for UI display."},"description":{"type":"string","description":"Longer description of what the prompt does."},"arguments":{"type":"array","description":"Arguments the client must (or may) supply when requesting this prompt.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Argument identifier; referenced from `messagesTemplate.template`."},"description":{"type":"string","description":"Optional human-readable description of the argument."},"required":{"type":"boolean","default":true,"description":"Whether the client must supply a value for this argument.\n\nServer default when omitted is `true` (the server writes\n`required: true` on any argument where the client didn't\nsend the field)."}},"required":["name"]}},"messagesTemplate":{"type":"array","description":"Ordered list of message templates rendered on `prompts/get`. Argument\nvalues from the request are substituted into each `template` string\nbefore returning.\n","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Message author role. Only `user` and `assistant` are accepted;\n`system` returns `enum` on `role`.\n"},"contentType":{"type":"string","enum":["text","image","audio","resource"],"default":"text","description":"Content modality for the rendered message. `pdf`/`video` and\nother values are rejected with 422 `enum`.\n\n`image` and `audio` require `mimeType` — omitting it returns\n422 `mcp_server_prompt_mimetype_required`. `text` and\n`resource` accept the message with no `mimeType`.\n"},"mimeType":{"type":"string","description":"MIME type for binary content (e.g. `image/png`, `audio/wav`).\nRequired when `contentType` is `image` or `audio`; optional\nfor `resource`; ignored for `text`.\n"},"template":{"type":"string","description":"Template body. May reference declared `arguments` via the MCP\ntemplate syntax; the server substitutes values on `prompts/get`.\n"}},"required":["role","template"]}}},"required":["name"]},"OAuthConfig":{"type":"object","description":"OAuth 2.0 resource-server configuration for the MCP server.\n\nWhen present, MCP clients must present a Bearer access token issued by the\nconfigured `issuerURL` and carrying the configured `audience`. Tokens are\nvalidated against the issuer's public keys (JWKS). If `useIntrospection`\nis enabled, opaque tokens are also accepted and validated via RFC 7662\nintrospection using `clientId` / `clientSecret`.\n","properties":{"issuerURL":{"type":"string","format":"uri","description":"OAuth 2.0 issuer URL.\n\nMust be a well-formed URL with an explicit scheme — bare hostnames\nand protocol-less values are rejected with 422 `invalid_uri`.\nIn practice `http://` and `https://` are the intended schemes; the\nserver's error message advertises http/https only, though the\nvalidator also accepts other schemes (e.g. `ftp://`). Don't rely\non the non-http(s) path — use `https://` for production issuers."},"audience":{"type":"string","description":"Expected `aud` claim on incoming access tokens. Required whenever\n`oauth` is present — omitting it returns `missing_required_field`\non `oauth.audience`.\n"},"useIntrospection":{"type":"boolean","default":false,"description":"When `true`, opaque access tokens are validated by calling the\nissuer's RFC 7662 introspection endpoint using `clientId` /\n`clientSecret`. When `false`, only JWT access tokens are accepted.\n"},"scopes":{"type":"array","description":"Required OAuth scopes. Incoming tokens must carry every listed scope.\n\nRejected values return `enum` / `invalid_field_value` on\n`oauth.scopes.<index>`.\n","items":{"type":"string","enum":["mcp:read","mcp:write"]}},"clientId":{"type":["string","null"],"description":"OAuth client id used when introspecting opaque tokens. Required\nwhen `useIntrospection` is `true`.\n"},"clientSecret":{"type":["string","null"],"description":"OAuth client secret used with `clientId` for introspection. Masked\nas `\"******\"` in response payloads; sending the masked value on\nPUT is treated as \"leave unchanged\".\n"}},"required":["issuerURL","audience"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/mcpservers":{"get":{"summary":"List MCP servers","description":"Returns a list of all MCP servers configured in the account.\nIf no MCP servers exist in the account, a 204 response with no body will be returned.\n","operationId":"listMcpServers","tags":["MCP Servers"],"parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Successfully retrieved list of MCP servers","headers":{"Link":{"description":"RFC-5988 pagination links. When more pages remain, includes a `<...>; rel=\"next\"` entry;\nabsent on the final page.\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"204":{"description":"No MCP servers exist in the account"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create an MCP server

> Creates a new MCP server that exposes tools and APIs as MCP-compatible endpoints.\
> \
> The server's \`relativeURI\` must be unique per account and follow 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 or API within the server must also be enabled.<br>

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating an MCP server.\n\nMCP servers expose Celigo tools and builder-mode APIs as MCP-compatible endpoints\nfor consumption by AI agents and MCP clients.\n","properties":{"name":{"type":"string","maxLength":300,"description":"Human-readable name for the MCP server.\n\nDisplayed in the UI to identify the server's purpose.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9_\\-]+$","description":"URI path segment for the MCP server endpoint.\n\nMust start with a forward slash followed by a single path segment containing\nonly alphanumeric characters, underscores, and hyphens. Must be unique\nper account.\n\nIf not provided, a `url` field can be supplied instead and the pathname\nwill be extracted automatically.\n"},"description":{"type":"string","maxLength":1000,"description":"Optional description of the MCP server's purpose and capabilities.\n"},"disabled":{"type":"boolean","default":true,"description":"Whether the MCP server is disabled.\n\nDisabled servers are not accessible to MCP clients. To enable a server,\nat least one tool or API within it must also be enabled.\n"},"tools":{"type":"array","description":"Tool entries that reference Celigo Tool resources.\n\nEach entry exposes a Tool as an MCP tool endpoint. Duplicate `_toolId`\nreferences are not allowed. Tool names must be unique across all tools\nand APIs in the server.\n","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries that reference Celigo builder-mode API resources.\n\nEach entry exposes an API as an MCP tool endpoint. Duplicate `_apiId`\nreferences are not allowed. Only builder-type APIs are supported.\nTool names must be unique across all tools and APIs in the server.\n","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Each\nprompt has a unique `name` and may declare `arguments` that clients\nsupply when requesting it via `prompts/get`.\n","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"$ref":"#/components/schemas/OAuthConfig"}},"required":["name","relativeURI"]},"IOTool":{"type":"object","description":"A tool entry within an MCP server that references a Tool resource.\n\nEach IO tool maps a Celigo Tool to an MCP-compatible tool endpoint. The tool's\ninput schema must have `type: \"object\"` to comply with the MCP specification.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"_toolId":{"type":"string","format":"objectId","description":"Reference to the Tool resource that this MCP tool exposes.\n\nThe referenced tool must exist, belong to the same user, and have an\ninput schema with `type: \"object\"`.\n"},"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this tool is disabled within the MCP server.\n\nDisabled tools are not exposed to MCP clients. At least one tool or API\nmust be enabled for the server itself to be enabled.\n"},"annotations":{"$ref":"#/components/schemas/Annotations"},"overrides":{"$ref":"#/components/schemas/Overrides"}},"required":["_toolId","name"]},"Annotations":{"type":"object","description":"MCP-standard annotations that hint at the behavior of a tool.\n\nThese annotations follow the Model Context Protocol specification and help\nAI agents and MCP clients understand how a tool behaves without executing it.\nAll fields are optional hints — they are not enforced by the server.\n","properties":{"title":{"type":"string","maxLength":300,"description":"Human-readable title for the tool, displayed in MCP client UIs.\n\nIf not provided, the tool's `name` field is used instead.\n"},"destructiveHint":{"type":"boolean","description":"Hints that the tool may perform destructive operations such as\ndeleting or permanently modifying data.\n"},"idempotentHint":{"type":"boolean","description":"Hints that calling the tool multiple times with the same input\nproduces the same result without additional side effects.\n"},"openWorldHint":{"type":"boolean","description":"Hints that the tool interacts with an open-world environment\n(e.g., external APIs) where results may vary between calls.\n"},"readOnlyHint":{"type":"boolean","description":"Hints that the tool only reads data and does not modify any state.\n"}}},"Overrides":{"type":"object","description":"Per-server overrides for a tool's internal resources.\n\nWhen a tool is added to an MCP server, its connections, exports, imports,\nand routers can be customized for this specific server context without\nmodifying the underlying tool definition. This enables reusing the same\ntool across multiple MCP servers with different configurations.\n","properties":{"connections":{"type":"array","description":"Connection overrides. Each entry maps an abstract connection reference\nin the tool to a concrete connection resource for this server.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"The abstract connection identifier from the tool definition.\nThis is the connection reference that will be replaced.\n"},"_id":{"type":"string","format":"objectId","description":"The concrete connection resource to use in place of the abstract reference.\n"},"_borrowConcurrencyFromConnectionId":{"type":"string","description":"Optional connection from which to borrow concurrency limits.\n"}},"required":["_abstractId"]}},"exports":{"type":"array","description":"Export (lookup) overrides. Customize export resources used within the tool,\nincluding connection bindings, scheduling, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract export identifier from the tool definition"},"_id":{"type":"string","format":"objectId","description":"Concrete export resource to use"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this export"},"type":{"type":"string","enum":["webhook","distributed","test","delta","once","tranlinedelta","simple","blob","all"],"description":"Override the export type"},"pageSize":{"type":"number","description":"Override the page size for pagination"},"skipRetries":{"type":"boolean","description":"Whether to skip retries on failure"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}}},"required":["_abstractId"]}},"imports":{"type":"array","description":"Import overrides. Customize import resources used within the tool,\nincluding connection bindings, hooks, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract import identifier from the tool definition"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this import"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}},"hooks":{"type":"object","description":"Override script hooks","properties":{"preMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}},"postMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}}}}},"required":["_abstractId"]}},"routers":{"type":"array","description":"Router overrides. Customize routing behavior for specific branches\nwithin the tool, including branch filters and routing strategies.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract router identifier from the tool definition"},"name":{"type":"string","description":"Override the router name"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch","all_matching_branches"],"description":"Override the routing strategy"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Override the routing evaluation method"},"script":{"type":"object","description":"Override the router script","properties":{"_scriptId":{"type":"string","format":"objectId"},"function":{"type":"string"}}},"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"},"description":{"type":"string","description":"Override the branch description"},"inputFilter":{"type":"object","description":"Override the branch filter criteria","properties":{"version":{"type":"string","enum":["1"]},"rules":{"type":"array","items":{}}}}}}}},"required":["_abstractId"]}}}},"ApiTool":{"type":"object","description":"An API entry within an MCP server that references a builder-mode API resource.\n\nEach API tool maps a Celigo API to an MCP-compatible tool endpoint. Only\nbuilder-type APIs (not script-type) can be used in MCP servers.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"_apiId":{"type":"string","format":"objectId","description":"Reference to the API resource that this MCP tool exposes.\n\nThe referenced API must exist, belong to the same user, and be of\ntype \"builder\" (script-type APIs are not supported).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this API tool is disabled within the MCP server.\n\nDisabled API tools are not exposed to MCP clients.\n"}},"required":["name","_apiId"]},"Prompt":{"type":"object","description":"A prompt template exposed to MCP clients by this server.\n\nMCP prompts are named templates that clients can request with a set of\narguments; the server substitutes the arguments into `messagesTemplate`\nand returns the resulting message list. Prompt names must be unique\nacross all prompts on the server.\n","properties":{"name":{"type":"string","description":"Prompt identifier exposed to MCP clients. Used by clients to request\nthis prompt via `prompts/get`.\n\nMust be unique within the server's `prompts[]`. Duplicates return\n422 `mcp_server_duplicate_prompt_name` on `prompts.<index>.name`."},"title":{"type":"string","description":"Short human-readable title for UI display."},"description":{"type":"string","description":"Longer description of what the prompt does."},"arguments":{"type":"array","description":"Arguments the client must (or may) supply when requesting this prompt.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Argument identifier; referenced from `messagesTemplate.template`."},"description":{"type":"string","description":"Optional human-readable description of the argument."},"required":{"type":"boolean","default":true,"description":"Whether the client must supply a value for this argument.\n\nServer default when omitted is `true` (the server writes\n`required: true` on any argument where the client didn't\nsend the field)."}},"required":["name"]}},"messagesTemplate":{"type":"array","description":"Ordered list of message templates rendered on `prompts/get`. Argument\nvalues from the request are substituted into each `template` string\nbefore returning.\n","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Message author role. Only `user` and `assistant` are accepted;\n`system` returns `enum` on `role`.\n"},"contentType":{"type":"string","enum":["text","image","audio","resource"],"default":"text","description":"Content modality for the rendered message. `pdf`/`video` and\nother values are rejected with 422 `enum`.\n\n`image` and `audio` require `mimeType` — omitting it returns\n422 `mcp_server_prompt_mimetype_required`. `text` and\n`resource` accept the message with no `mimeType`.\n"},"mimeType":{"type":"string","description":"MIME type for binary content (e.g. `image/png`, `audio/wav`).\nRequired when `contentType` is `image` or `audio`; optional\nfor `resource`; ignored for `text`.\n"},"template":{"type":"string","description":"Template body. May reference declared `arguments` via the MCP\ntemplate syntax; the server substitutes values on `prompts/get`.\n"}},"required":["role","template"]}}},"required":["name"]},"OAuthConfig":{"type":"object","description":"OAuth 2.0 resource-server configuration for the MCP server.\n\nWhen present, MCP clients must present a Bearer access token issued by the\nconfigured `issuerURL` and carrying the configured `audience`. Tokens are\nvalidated against the issuer's public keys (JWKS). If `useIntrospection`\nis enabled, opaque tokens are also accepted and validated via RFC 7662\nintrospection using `clientId` / `clientSecret`.\n","properties":{"issuerURL":{"type":"string","format":"uri","description":"OAuth 2.0 issuer URL.\n\nMust be a well-formed URL with an explicit scheme — bare hostnames\nand protocol-less values are rejected with 422 `invalid_uri`.\nIn practice `http://` and `https://` are the intended schemes; the\nserver's error message advertises http/https only, though the\nvalidator also accepts other schemes (e.g. `ftp://`). Don't rely\non the non-http(s) path — use `https://` for production issuers."},"audience":{"type":"string","description":"Expected `aud` claim on incoming access tokens. Required whenever\n`oauth` is present — omitting it returns `missing_required_field`\non `oauth.audience`.\n"},"useIntrospection":{"type":"boolean","default":false,"description":"When `true`, opaque access tokens are validated by calling the\nissuer's RFC 7662 introspection endpoint using `clientId` /\n`clientSecret`. When `false`, only JWT access tokens are accepted.\n"},"scopes":{"type":"array","description":"Required OAuth scopes. Incoming tokens must carry every listed scope.\n\nRejected values return `enum` / `invalid_field_value` on\n`oauth.scopes.<index>`.\n","items":{"type":"string","enum":["mcp:read","mcp:write"]}},"clientId":{"type":["string","null"],"description":"OAuth client id used when introspecting opaque tokens. Required\nwhen `useIntrospection` is `true`.\n"},"clientSecret":{"type":["string","null"],"description":"OAuth client secret used with `clientId` for introspection. Masked\nas `\"******\"` in response payloads; sending the masked value on\nPUT is treated as \"leave unchanged\".\n"}},"required":["issuerURL","audience"]},"Response":{"type":"object","description":"Response schema for MCP server operations.\n\nContains the complete MCP server configuration including metadata,\ntool entries, API entries, and their override settings.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the MCP server"},"_userId":{"type":"string","format":"objectId","readOnly":true,"description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the MCP server"},"relativeURI":{"type":"string","description":"URI path segment for the MCP server endpoint"},"description":{"type":"string","description":"Description of the MCP server's purpose"},"disabled":{"type":"boolean","description":"Whether the MCP server is disabled"},"tools":{"type":"array","description":"Tool entries referencing Celigo Tool resources","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries referencing Celigo builder-mode API resources","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Always\npresent in responses — servers with no prompts configured return\n`prompts: []`.","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"description":"OAuth 2.0 configuration. Always present in responses — servers\nwithout OAuth configured still return `oauth: {useIntrospection: false}`.","allOf":[{"$ref":"#/components/schemas/OAuthConfig"}]},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was soft-deleted.\n\nOnly present for deleted servers. The server will be permanently\nremoved 30 days after this timestamp.\n"}}},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/mcpservers":{"post":{"summary":"Create an MCP server","description":"Creates a new MCP server that exposes tools and APIs as MCP-compatible endpoints.\n\nThe server's `relativeURI` must be unique per account and follow the pattern\n`/<segment>` where the segment contains only alphanumeric characters, underscores,\nand hyphens.\n\nThe server is created in a disabled state by default. To enable it, at least one\ntool or API within the server must also be enabled.\n","operationId":"createMcpServer","tags":["MCP Servers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"MCP server created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Get an MCP server

> Returns the complete configuration of a specific MCP server, including\
> its tools, APIs, and override settings.<br>

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Response schema for MCP server operations.\n\nContains the complete MCP server configuration including metadata,\ntool entries, API entries, and their override settings.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the MCP server"},"_userId":{"type":"string","format":"objectId","readOnly":true,"description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the MCP server"},"relativeURI":{"type":"string","description":"URI path segment for the MCP server endpoint"},"description":{"type":"string","description":"Description of the MCP server's purpose"},"disabled":{"type":"boolean","description":"Whether the MCP server is disabled"},"tools":{"type":"array","description":"Tool entries referencing Celigo Tool resources","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries referencing Celigo builder-mode API resources","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Always\npresent in responses — servers with no prompts configured return\n`prompts: []`.","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"description":"OAuth 2.0 configuration. Always present in responses — servers\nwithout OAuth configured still return `oauth: {useIntrospection: false}`.","allOf":[{"$ref":"#/components/schemas/OAuthConfig"}]},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was soft-deleted.\n\nOnly present for deleted servers. The server will be permanently\nremoved 30 days after this timestamp.\n"}}},"IOTool":{"type":"object","description":"A tool entry within an MCP server that references a Tool resource.\n\nEach IO tool maps a Celigo Tool to an MCP-compatible tool endpoint. The tool's\ninput schema must have `type: \"object\"` to comply with the MCP specification.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"_toolId":{"type":"string","format":"objectId","description":"Reference to the Tool resource that this MCP tool exposes.\n\nThe referenced tool must exist, belong to the same user, and have an\ninput schema with `type: \"object\"`.\n"},"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this tool is disabled within the MCP server.\n\nDisabled tools are not exposed to MCP clients. At least one tool or API\nmust be enabled for the server itself to be enabled.\n"},"annotations":{"$ref":"#/components/schemas/Annotations"},"overrides":{"$ref":"#/components/schemas/Overrides"}},"required":["_toolId","name"]},"Annotations":{"type":"object","description":"MCP-standard annotations that hint at the behavior of a tool.\n\nThese annotations follow the Model Context Protocol specification and help\nAI agents and MCP clients understand how a tool behaves without executing it.\nAll fields are optional hints — they are not enforced by the server.\n","properties":{"title":{"type":"string","maxLength":300,"description":"Human-readable title for the tool, displayed in MCP client UIs.\n\nIf not provided, the tool's `name` field is used instead.\n"},"destructiveHint":{"type":"boolean","description":"Hints that the tool may perform destructive operations such as\ndeleting or permanently modifying data.\n"},"idempotentHint":{"type":"boolean","description":"Hints that calling the tool multiple times with the same input\nproduces the same result without additional side effects.\n"},"openWorldHint":{"type":"boolean","description":"Hints that the tool interacts with an open-world environment\n(e.g., external APIs) where results may vary between calls.\n"},"readOnlyHint":{"type":"boolean","description":"Hints that the tool only reads data and does not modify any state.\n"}}},"Overrides":{"type":"object","description":"Per-server overrides for a tool's internal resources.\n\nWhen a tool is added to an MCP server, its connections, exports, imports,\nand routers can be customized for this specific server context without\nmodifying the underlying tool definition. This enables reusing the same\ntool across multiple MCP servers with different configurations.\n","properties":{"connections":{"type":"array","description":"Connection overrides. Each entry maps an abstract connection reference\nin the tool to a concrete connection resource for this server.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"The abstract connection identifier from the tool definition.\nThis is the connection reference that will be replaced.\n"},"_id":{"type":"string","format":"objectId","description":"The concrete connection resource to use in place of the abstract reference.\n"},"_borrowConcurrencyFromConnectionId":{"type":"string","description":"Optional connection from which to borrow concurrency limits.\n"}},"required":["_abstractId"]}},"exports":{"type":"array","description":"Export (lookup) overrides. Customize export resources used within the tool,\nincluding connection bindings, scheduling, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract export identifier from the tool definition"},"_id":{"type":"string","format":"objectId","description":"Concrete export resource to use"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this export"},"type":{"type":"string","enum":["webhook","distributed","test","delta","once","tranlinedelta","simple","blob","all"],"description":"Override the export type"},"pageSize":{"type":"number","description":"Override the page size for pagination"},"skipRetries":{"type":"boolean","description":"Whether to skip retries on failure"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}}},"required":["_abstractId"]}},"imports":{"type":"array","description":"Import overrides. Customize import resources used within the tool,\nincluding connection bindings, hooks, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract import identifier from the tool definition"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this import"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}},"hooks":{"type":"object","description":"Override script hooks","properties":{"preMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}},"postMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}}}}},"required":["_abstractId"]}},"routers":{"type":"array","description":"Router overrides. Customize routing behavior for specific branches\nwithin the tool, including branch filters and routing strategies.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract router identifier from the tool definition"},"name":{"type":"string","description":"Override the router name"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch","all_matching_branches"],"description":"Override the routing strategy"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Override the routing evaluation method"},"script":{"type":"object","description":"Override the router script","properties":{"_scriptId":{"type":"string","format":"objectId"},"function":{"type":"string"}}},"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"},"description":{"type":"string","description":"Override the branch description"},"inputFilter":{"type":"object","description":"Override the branch filter criteria","properties":{"version":{"type":"string","enum":["1"]},"rules":{"type":"array","items":{}}}}}}}},"required":["_abstractId"]}}}},"ApiTool":{"type":"object","description":"An API entry within an MCP server that references a builder-mode API resource.\n\nEach API tool maps a Celigo API to an MCP-compatible tool endpoint. Only\nbuilder-type APIs (not script-type) can be used in MCP servers.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"_apiId":{"type":"string","format":"objectId","description":"Reference to the API resource that this MCP tool exposes.\n\nThe referenced API must exist, belong to the same user, and be of\ntype \"builder\" (script-type APIs are not supported).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this API tool is disabled within the MCP server.\n\nDisabled API tools are not exposed to MCP clients.\n"}},"required":["name","_apiId"]},"Prompt":{"type":"object","description":"A prompt template exposed to MCP clients by this server.\n\nMCP prompts are named templates that clients can request with a set of\narguments; the server substitutes the arguments into `messagesTemplate`\nand returns the resulting message list. Prompt names must be unique\nacross all prompts on the server.\n","properties":{"name":{"type":"string","description":"Prompt identifier exposed to MCP clients. Used by clients to request\nthis prompt via `prompts/get`.\n\nMust be unique within the server's `prompts[]`. Duplicates return\n422 `mcp_server_duplicate_prompt_name` on `prompts.<index>.name`."},"title":{"type":"string","description":"Short human-readable title for UI display."},"description":{"type":"string","description":"Longer description of what the prompt does."},"arguments":{"type":"array","description":"Arguments the client must (or may) supply when requesting this prompt.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Argument identifier; referenced from `messagesTemplate.template`."},"description":{"type":"string","description":"Optional human-readable description of the argument."},"required":{"type":"boolean","default":true,"description":"Whether the client must supply a value for this argument.\n\nServer default when omitted is `true` (the server writes\n`required: true` on any argument where the client didn't\nsend the field)."}},"required":["name"]}},"messagesTemplate":{"type":"array","description":"Ordered list of message templates rendered on `prompts/get`. Argument\nvalues from the request are substituted into each `template` string\nbefore returning.\n","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Message author role. Only `user` and `assistant` are accepted;\n`system` returns `enum` on `role`.\n"},"contentType":{"type":"string","enum":["text","image","audio","resource"],"default":"text","description":"Content modality for the rendered message. `pdf`/`video` and\nother values are rejected with 422 `enum`.\n\n`image` and `audio` require `mimeType` — omitting it returns\n422 `mcp_server_prompt_mimetype_required`. `text` and\n`resource` accept the message with no `mimeType`.\n"},"mimeType":{"type":"string","description":"MIME type for binary content (e.g. `image/png`, `audio/wav`).\nRequired when `contentType` is `image` or `audio`; optional\nfor `resource`; ignored for `text`.\n"},"template":{"type":"string","description":"Template body. May reference declared `arguments` via the MCP\ntemplate syntax; the server substitutes values on `prompts/get`.\n"}},"required":["role","template"]}}},"required":["name"]},"OAuthConfig":{"type":"object","description":"OAuth 2.0 resource-server configuration for the MCP server.\n\nWhen present, MCP clients must present a Bearer access token issued by the\nconfigured `issuerURL` and carrying the configured `audience`. Tokens are\nvalidated against the issuer's public keys (JWKS). If `useIntrospection`\nis enabled, opaque tokens are also accepted and validated via RFC 7662\nintrospection using `clientId` / `clientSecret`.\n","properties":{"issuerURL":{"type":"string","format":"uri","description":"OAuth 2.0 issuer URL.\n\nMust be a well-formed URL with an explicit scheme — bare hostnames\nand protocol-less values are rejected with 422 `invalid_uri`.\nIn practice `http://` and `https://` are the intended schemes; the\nserver's error message advertises http/https only, though the\nvalidator also accepts other schemes (e.g. `ftp://`). Don't rely\non the non-http(s) path — use `https://` for production issuers."},"audience":{"type":"string","description":"Expected `aud` claim on incoming access tokens. Required whenever\n`oauth` is present — omitting it returns `missing_required_field`\non `oauth.audience`.\n"},"useIntrospection":{"type":"boolean","default":false,"description":"When `true`, opaque access tokens are validated by calling the\nissuer's RFC 7662 introspection endpoint using `clientId` /\n`clientSecret`. When `false`, only JWT access tokens are accepted.\n"},"scopes":{"type":"array","description":"Required OAuth scopes. Incoming tokens must carry every listed scope.\n\nRejected values return `enum` / `invalid_field_value` on\n`oauth.scopes.<index>`.\n","items":{"type":"string","enum":["mcp:read","mcp:write"]}},"clientId":{"type":["string","null"],"description":"OAuth client id used when introspecting opaque tokens. Required\nwhen `useIntrospection` is `true`.\n"},"clientSecret":{"type":["string","null"],"description":"OAuth client secret used with `clientId` for introspection. Masked\nas `\"******\"` in response payloads; sending the masked value on\nPUT is treated as \"leave unchanged\".\n"}},"required":["issuerURL","audience"]},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/mcpservers/{_id}":{"get":{"summary":"Get an MCP server","description":"Returns the complete configuration of a specific MCP server, including\nits tools, APIs, and override settings.\n","operationId":"getMcpServerById","tags":["MCP Servers"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the MCP server","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"MCP server retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update an MCP server

> Updates an existing MCP server with the provided configuration.\
> This replaces the full server configuration including tools and APIs.<br>

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating an MCP server.\n\nMCP servers expose Celigo tools and builder-mode APIs as MCP-compatible endpoints\nfor consumption by AI agents and MCP clients.\n","properties":{"name":{"type":"string","maxLength":300,"description":"Human-readable name for the MCP server.\n\nDisplayed in the UI to identify the server's purpose.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9_\\-]+$","description":"URI path segment for the MCP server endpoint.\n\nMust start with a forward slash followed by a single path segment containing\nonly alphanumeric characters, underscores, and hyphens. Must be unique\nper account.\n\nIf not provided, a `url` field can be supplied instead and the pathname\nwill be extracted automatically.\n"},"description":{"type":"string","maxLength":1000,"description":"Optional description of the MCP server's purpose and capabilities.\n"},"disabled":{"type":"boolean","default":true,"description":"Whether the MCP server is disabled.\n\nDisabled servers are not accessible to MCP clients. To enable a server,\nat least one tool or API within it must also be enabled.\n"},"tools":{"type":"array","description":"Tool entries that reference Celigo Tool resources.\n\nEach entry exposes a Tool as an MCP tool endpoint. Duplicate `_toolId`\nreferences are not allowed. Tool names must be unique across all tools\nand APIs in the server.\n","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries that reference Celigo builder-mode API resources.\n\nEach entry exposes an API as an MCP tool endpoint. Duplicate `_apiId`\nreferences are not allowed. Only builder-type APIs are supported.\nTool names must be unique across all tools and APIs in the server.\n","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Each\nprompt has a unique `name` and may declare `arguments` that clients\nsupply when requesting it via `prompts/get`.\n","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"$ref":"#/components/schemas/OAuthConfig"}},"required":["name","relativeURI"]},"IOTool":{"type":"object","description":"A tool entry within an MCP server that references a Tool resource.\n\nEach IO tool maps a Celigo Tool to an MCP-compatible tool endpoint. The tool's\ninput schema must have `type: \"object\"` to comply with the MCP specification.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"_toolId":{"type":"string","format":"objectId","description":"Reference to the Tool resource that this MCP tool exposes.\n\nThe referenced tool must exist, belong to the same user, and have an\ninput schema with `type: \"object\"`.\n"},"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this tool is disabled within the MCP server.\n\nDisabled tools are not exposed to MCP clients. At least one tool or API\nmust be enabled for the server itself to be enabled.\n"},"annotations":{"$ref":"#/components/schemas/Annotations"},"overrides":{"$ref":"#/components/schemas/Overrides"}},"required":["_toolId","name"]},"Annotations":{"type":"object","description":"MCP-standard annotations that hint at the behavior of a tool.\n\nThese annotations follow the Model Context Protocol specification and help\nAI agents and MCP clients understand how a tool behaves without executing it.\nAll fields are optional hints — they are not enforced by the server.\n","properties":{"title":{"type":"string","maxLength":300,"description":"Human-readable title for the tool, displayed in MCP client UIs.\n\nIf not provided, the tool's `name` field is used instead.\n"},"destructiveHint":{"type":"boolean","description":"Hints that the tool may perform destructive operations such as\ndeleting or permanently modifying data.\n"},"idempotentHint":{"type":"boolean","description":"Hints that calling the tool multiple times with the same input\nproduces the same result without additional side effects.\n"},"openWorldHint":{"type":"boolean","description":"Hints that the tool interacts with an open-world environment\n(e.g., external APIs) where results may vary between calls.\n"},"readOnlyHint":{"type":"boolean","description":"Hints that the tool only reads data and does not modify any state.\n"}}},"Overrides":{"type":"object","description":"Per-server overrides for a tool's internal resources.\n\nWhen a tool is added to an MCP server, its connections, exports, imports,\nand routers can be customized for this specific server context without\nmodifying the underlying tool definition. This enables reusing the same\ntool across multiple MCP servers with different configurations.\n","properties":{"connections":{"type":"array","description":"Connection overrides. Each entry maps an abstract connection reference\nin the tool to a concrete connection resource for this server.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"The abstract connection identifier from the tool definition.\nThis is the connection reference that will be replaced.\n"},"_id":{"type":"string","format":"objectId","description":"The concrete connection resource to use in place of the abstract reference.\n"},"_borrowConcurrencyFromConnectionId":{"type":"string","description":"Optional connection from which to borrow concurrency limits.\n"}},"required":["_abstractId"]}},"exports":{"type":"array","description":"Export (lookup) overrides. Customize export resources used within the tool,\nincluding connection bindings, scheduling, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract export identifier from the tool definition"},"_id":{"type":"string","format":"objectId","description":"Concrete export resource to use"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this export"},"type":{"type":"string","enum":["webhook","distributed","test","delta","once","tranlinedelta","simple","blob","all"],"description":"Override the export type"},"pageSize":{"type":"number","description":"Override the page size for pagination"},"skipRetries":{"type":"boolean","description":"Whether to skip retries on failure"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}}},"required":["_abstractId"]}},"imports":{"type":"array","description":"Import overrides. Customize import resources used within the tool,\nincluding connection bindings, hooks, response mappings, and\nadaptor-specific settings.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract import identifier from the tool definition"},"_connectionId":{"type":"string","format":"objectId","description":"Override the connection used by this import"},"proceedOnFailure":{"type":"boolean","description":"Whether to continue processing on failure"},"responseMapping":{"type":"object","description":"Override the response field mappings","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}},"lists":{"type":"array","items":{"type":"object","properties":{"generate":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"extract":{"type":"string"},"generate":{"type":"string"}}}}}}}}},"hooks":{"type":"object","description":"Override script hooks","properties":{"preMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}},"postMap":{"type":"object","properties":{"function":{"type":"string"},"_scriptId":{"type":"string","format":"objectId"}}}}}},"required":["_abstractId"]}},"routers":{"type":"array","description":"Router overrides. Customize routing behavior for specific branches\nwithin the tool, including branch filters and routing strategies.\n","items":{"type":"object","properties":{"_abstractId":{"type":"string","description":"Abstract router identifier from the tool definition"},"name":{"type":"string","description":"Override the router name"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch","all_matching_branches"],"description":"Override the routing strategy"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Override the routing evaluation method"},"script":{"type":"object","description":"Override the router script","properties":{"_scriptId":{"type":"string","format":"objectId"},"function":{"type":"string"}}},"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"},"description":{"type":"string","description":"Override the branch description"},"inputFilter":{"type":"object","description":"Override the branch filter criteria","properties":{"version":{"type":"string","enum":["1"]},"rules":{"type":"array","items":{}}}}}}}},"required":["_abstractId"]}}}},"ApiTool":{"type":"object","description":"An API entry within an MCP server that references a builder-mode API resource.\n\nEach API tool maps a Celigo API to an MCP-compatible tool endpoint. Only\nbuilder-type APIs (not script-type) can be used in MCP servers.\n\nTool names across all tools and APIs within the same MCP server must be unique\nand follow the MCP naming convention (alphanumeric, underscores, hyphens, dots only).\n","properties":{"name":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9_\\-.]+$","description":"The MCP tool name exposed to clients.\n\nMust be unique across all tools and APIs within this MCP server.\nOnly alphanumeric characters, underscores, hyphens, and dots are allowed.\nMaximum length: 128 characters (enforced by validation).\n"},"_apiId":{"type":"string","format":"objectId","description":"Reference to the API resource that this MCP tool exposes.\n\nThe referenced API must exist, belong to the same user, and be of\ntype \"builder\" (script-type APIs are not supported).\n"},"disabled":{"type":"boolean","default":true,"description":"Whether this API tool is disabled within the MCP server.\n\nDisabled API tools are not exposed to MCP clients.\n"}},"required":["name","_apiId"]},"Prompt":{"type":"object","description":"A prompt template exposed to MCP clients by this server.\n\nMCP prompts are named templates that clients can request with a set of\narguments; the server substitutes the arguments into `messagesTemplate`\nand returns the resulting message list. Prompt names must be unique\nacross all prompts on the server.\n","properties":{"name":{"type":"string","description":"Prompt identifier exposed to MCP clients. Used by clients to request\nthis prompt via `prompts/get`.\n\nMust be unique within the server's `prompts[]`. Duplicates return\n422 `mcp_server_duplicate_prompt_name` on `prompts.<index>.name`."},"title":{"type":"string","description":"Short human-readable title for UI display."},"description":{"type":"string","description":"Longer description of what the prompt does."},"arguments":{"type":"array","description":"Arguments the client must (or may) supply when requesting this prompt.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Argument identifier; referenced from `messagesTemplate.template`."},"description":{"type":"string","description":"Optional human-readable description of the argument."},"required":{"type":"boolean","default":true,"description":"Whether the client must supply a value for this argument.\n\nServer default when omitted is `true` (the server writes\n`required: true` on any argument where the client didn't\nsend the field)."}},"required":["name"]}},"messagesTemplate":{"type":"array","description":"Ordered list of message templates rendered on `prompts/get`. Argument\nvalues from the request are substituted into each `template` string\nbefore returning.\n","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"description":"Message author role. Only `user` and `assistant` are accepted;\n`system` returns `enum` on `role`.\n"},"contentType":{"type":"string","enum":["text","image","audio","resource"],"default":"text","description":"Content modality for the rendered message. `pdf`/`video` and\nother values are rejected with 422 `enum`.\n\n`image` and `audio` require `mimeType` — omitting it returns\n422 `mcp_server_prompt_mimetype_required`. `text` and\n`resource` accept the message with no `mimeType`.\n"},"mimeType":{"type":"string","description":"MIME type for binary content (e.g. `image/png`, `audio/wav`).\nRequired when `contentType` is `image` or `audio`; optional\nfor `resource`; ignored for `text`.\n"},"template":{"type":"string","description":"Template body. May reference declared `arguments` via the MCP\ntemplate syntax; the server substitutes values on `prompts/get`.\n"}},"required":["role","template"]}}},"required":["name"]},"OAuthConfig":{"type":"object","description":"OAuth 2.0 resource-server configuration for the MCP server.\n\nWhen present, MCP clients must present a Bearer access token issued by the\nconfigured `issuerURL` and carrying the configured `audience`. Tokens are\nvalidated against the issuer's public keys (JWKS). If `useIntrospection`\nis enabled, opaque tokens are also accepted and validated via RFC 7662\nintrospection using `clientId` / `clientSecret`.\n","properties":{"issuerURL":{"type":"string","format":"uri","description":"OAuth 2.0 issuer URL.\n\nMust be a well-formed URL with an explicit scheme — bare hostnames\nand protocol-less values are rejected with 422 `invalid_uri`.\nIn practice `http://` and `https://` are the intended schemes; the\nserver's error message advertises http/https only, though the\nvalidator also accepts other schemes (e.g. `ftp://`). Don't rely\non the non-http(s) path — use `https://` for production issuers."},"audience":{"type":"string","description":"Expected `aud` claim on incoming access tokens. Required whenever\n`oauth` is present — omitting it returns `missing_required_field`\non `oauth.audience`.\n"},"useIntrospection":{"type":"boolean","default":false,"description":"When `true`, opaque access tokens are validated by calling the\nissuer's RFC 7662 introspection endpoint using `clientId` /\n`clientSecret`. When `false`, only JWT access tokens are accepted.\n"},"scopes":{"type":"array","description":"Required OAuth scopes. Incoming tokens must carry every listed scope.\n\nRejected values return `enum` / `invalid_field_value` on\n`oauth.scopes.<index>`.\n","items":{"type":"string","enum":["mcp:read","mcp:write"]}},"clientId":{"type":["string","null"],"description":"OAuth client id used when introspecting opaque tokens. Required\nwhen `useIntrospection` is `true`.\n"},"clientSecret":{"type":["string","null"],"description":"OAuth client secret used with `clientId` for introspection. Masked\nas `\"******\"` in response payloads; sending the masked value on\nPUT is treated as \"leave unchanged\".\n"}},"required":["issuerURL","audience"]},"Response":{"type":"object","description":"Response schema for MCP server operations.\n\nContains the complete MCP server configuration including metadata,\ntool entries, API entries, and their override settings.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the MCP server"},"_userId":{"type":"string","format":"objectId","readOnly":true,"description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the MCP server"},"relativeURI":{"type":"string","description":"URI path segment for the MCP server endpoint"},"description":{"type":"string","description":"Description of the MCP server's purpose"},"disabled":{"type":"boolean","description":"Whether the MCP server is disabled"},"tools":{"type":"array","description":"Tool entries referencing Celigo Tool resources","items":{"$ref":"#/components/schemas/IOTool"}},"apis":{"type":"array","description":"API entries referencing Celigo builder-mode API resources","items":{"$ref":"#/components/schemas/ApiTool"}},"prompts":{"type":"array","description":"Prompt templates exposed to MCP clients under this server. Always\npresent in responses — servers with no prompts configured return\n`prompts: []`.","items":{"$ref":"#/components/schemas/Prompt"}},"oauth":{"description":"OAuth 2.0 configuration. Always present in responses — servers\nwithout OAuth configured still return `oauth: {useIntrospection: false}`.","allOf":[{"$ref":"#/components/schemas/OAuthConfig"}]},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the MCP server was soft-deleted.\n\nOnly present for deleted servers. The server will be permanently\nremoved 30 days after this timestamp.\n"}}},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/mcpservers/{_id}":{"put":{"summary":"Update an MCP server","description":"Updates an existing MCP server with the provided configuration.\nThis replaces the full server configuration including tools and APIs.\n","operationId":"updateMcpServer","tags":["MCP Servers"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the MCP server","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"MCP server updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"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"}}}}}}
```

## Delete an MCP server

> Deletes an MCP server. The server is soft-deleted and retained for 30 days\
> before permanent removal.<br>

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/mcpservers/{_id}":{"delete":{"summary":"Delete an MCP server","description":"Deletes an MCP server. The server is soft-deleted and retained for 30 days\nbefore permanent removal.\n","operationId":"deleteMcpServer","tags":["MCP Servers"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the MCP server","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"MCP server deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Patch an MCP server

> Partially updates an MCP server using a JSON Patch document (RFC 6902).\
> Only the \`replace\` operation is supported, and only on the following\
> whitelisted paths:\
> \
> \| Path | Description |\
> \|------|-------------|\
> \| \`/name\` | Server display name |\
> \| \`/disabled\` | Enable or disable the server (boolean) |\
> \
> All other paths are rejected with \`422\`.

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"JsonPatchRequest":{"type":"array","description":"A JSON Patch document (RFC 6902). Send an array of patch\noperations. Only the `replace` operation is supported, and only\non whitelisted fields — all other paths are rejected with 422.","minItems":1,"items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"JsonPatchOperation":{"type":"object","description":"A single JSON Patch operation (RFC 6902).","required":["op","path"],"properties":{"op":{"type":"string","enum":["replace"],"description":"The operation to perform. Only `replace` is supported."},"path":{"type":"string","description":"JSON Pointer (RFC 6901) to the field to patch. Only\nwhitelisted paths are accepted — unlisted paths return\n`422` with `\"<path> is not a whitelisted property\"`."},"value":{"description":"The new value to set at the given path."}}},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/mcpservers/{_id}":{"patch":{"summary":"Patch an MCP server","description":"Partially updates an MCP server using a JSON Patch document (RFC 6902).\nOnly the `replace` operation is supported, and only on the following\nwhitelisted paths:\n\n| Path | Description |\n|------|-------------|\n| `/name` | Server display name |\n| `/disabled` | Enable or disable the server (boolean) |\n\nAll other paths are rejected with `422`.","operationId":"patchMcpServer","tags":["MCP Servers"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the MCP server","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonPatchRequest"}}}},"responses":{"204":{"description":"MCP server patched successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## List dependencies of an MCP server

> 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.\
> \
> AI guidance:\
> \- An empty object \`{}\` means no other resources depend on the target.\
> &#x20; This is also returned for a well-formatted but nonexistent id.

```json
{"openapi":"3.1.0","info":{"title":"MCP Servers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"paths":{"type":"array","description":"JSON-path-style pointers within the dependent resource's document\nthat reference the target resource.\n","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of ids that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of id strings.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/mcpservers/{_id}/dependencies":{"get":{"operationId":"listMcpServerDependencies","tags":["MCP Servers"],"summary":"List dependencies of an MCP server","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries.\n\nAI guidance:\n- An empty object `{}` means no other resources depend on the target.\n  This is also returned for a well-formatted but nonexistent id.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://developer.celigo.com/api/api-reference/mcp-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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