> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/mcp/tools.md).

# Tools

## Tools

Celigo Platform MCP exposes a compact, composable toolset. Your client fetches the full list and JSON schemas at runtime via the MCP `tools/list` method, so the catalog is always current and you never configure individual tools. You also never call them by hand: you ask in plain language and the agent chooses and chains the tools. This page explains the model and lists every tool, with the kind of prompt that triggers each group.

### The model

Rather than one tool per CRUD verb, the catalog is built from three patterns:

* **`list_*` reads.** Each resource has one reader that does double duty: omit `_id` to list a collection, or set `_id` to fetch one full resource. So `list_flows` lists flows, and `list_flows` with an `_id` returns that flow with all its steps. List responses use a compact summary projection you can widen or narrow with `include` and `exclude`.
* **`upsert_*` writes.** One writer per resource. Omit `_id` to create (POST, the server assigns the id); provide `_id` to update (PUT, a full-document replace). Read the resource first, change the fields you want, write the whole document back.
* **`delete_resource`.** One generic delete for every resource family, chosen with `resourceType`. A best-effort dependency pre-flight runs first and returns any dependents as advisory `warnings[]`, but the delete always proceeds — dependents never block it. Only an iClient delete [waits for your confirmation](#calls-that-wait-for-your-confirmation).

A few operation tools sit outside the pattern: `run_flow`, `run_export`, and `patch_flow`, the run inspectors (`list_flow_runs`, `list_current_jobs`, `cancel_flow_run`), the error-triage tools, the execution-log reader, the event-report pair, the lookup-cache-data tools, the EDI transaction tools, the marketplace pair, the Integration App settings pair, the user-management pair, the Celigo Storage file tools, `get_schema`, `get_skill`, `search_docs`, and `submit_feedback`. They are all in the catalog below.

Why this shape: collapsing list and get into one tool, and create and update into one tool, keeps the catalog small and mirrors how agents actually work. They list to find an `_id`, then act on it. Fewer tools means less to load and less to get wrong.

Every tool also declares a display title and standard [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) (read-only, destructive, idempotent, open-world), so clients that understand them badge reads and writes correctly and can ask for confirmation before destructive calls. Five tools carry the open-world hint because they reach beyond your account: `run_flow`, `run_export`, `triage_flow_errors`, `upsert_mcp_server`, and `manage_user`.

### Fetching schemas on demand with `get_schema`

Resource and connector schemas are large, so they are not bundled into `tools/list`. Instead, the agent calls `get_schema` to pull only what it needs, when it needs it. It takes a `target` and a `name`:

* `target: "resource"` returns the shape of a platform resource (`flow`, `export`, `connection`, and so on). Use `resource/sub` for adaptor-specific shapes like `connection/netsuite` or `import/http`, for shapes exports and imports share (`common/hooks`, `common/filter`, `common/lookups`, `common/mappings`, `common/form`), and for flow parts (`flow/page-generator`, `flow/page-processor`, `flow/router`). A bare resource name lists its sub-schemas in `availableSubSchemas`.
* `target: "connector"` returns an HTTP connector's definition by id or partial-name search, or native application metadata (record types and fields) when `name` is a connection `_id`, for example a NetSuite or Salesforce connection. HTTP connections have no native metadata; for one, pass its `http._httpConnectorId` to read its connector.
* `target: "connector_openapi"` returns the OpenAPI fragment for an HTTP connector's REST surface.

A schema longer than about 12,000 characters comes back as an outline (`outline: true`): each field's type, enum values, and required children, with the start of its description. To get one field's full schema, add `path`, a dotted field path such as `http.lookups`, `hooks.preMap`, or `schedule`. A `path` that matches nothing returns an `error` that names the fields at the level where it stopped.

A good build loop is: `get_schema` to learn the fields, construct the body, then `upsert_*`. That avoids guessing field names and burning calls on `422 Unprocessable Entity` validation errors. The schemas come from the same OpenAPI specs published in the [API reference](https://developer.celigo.com/api).

### Automatic composition

Agents chain tools on their own. Ask for flow details and the agent calls `list_flows` with the flow `_id`, sees the export and import references in the response, then calls `list_exports` and `list_imports` to resolve them, building a full picture without being told each step.

***

## Catalog

Every tool the server exposes, grouped by what it does. `list_*`, `get_*`, `run_export`, and `search_docs` are **reads**. Everything else — the `upsert_*` writers, `patch_flow`, `delete_resource`, `run_flow`, `cancel_flow_run`, `create_event_report`, the error-triage writers, the lookup-cache-data writers, `update_edi_fa_status`, `install_template`, `save_integration_app_settings`, `manage_user`, and the storage writers — **changes live data**, so a careful agent confirms before calling them. `submit_feedback` also writes, but only a feedback record sent to Celigo; nothing in your account changes.

> ⚠️ **Writes act on your real account, and `delete_resource` never blocks on dependents.** `upsert_*`, `patch_flow`, `run_flow`, `triage_flow_errors`, `install_template`, `save_integration_app_settings`, `manage_user`, and the `*_lookup_cache_data` writers change live data. `delete_resource` removes the target even when other resources depend on it — the dependency pre-flight reports dependents only as advisory `warnings[]` and never stops the delete. The server holds only a few calls for your confirmation (see below), so confirm the agent's plan before any write.

### Calls that wait for your confirmation

The server holds three kinds of call until you confirm them:

* **Purging a lookup cache.** `delete_lookup_cache_data` with `all: true`. The recycle bin can't restore cache entries.
* **Deleting an iClient.** `delete_resource` with `resourceType: "iclients"`. iClients don't go to the recycle bin.
* **Updating a shared step.** `upsert_export`, `upsert_import`, `upsert_ai_agent`, or `upsert_guardrail` with an `_id`, when two or more flows, Tools, or APIs use the step. The update changes the step in all of them.

A held call changes nothing. It returns the error `confirmation_required` with a `message` that says what the call would do and a `confirmationToken`. The agent asks you, and after you say yes it sends the same call again with the token. A token works only for a call with the same arguments, and `expiresInSeconds` in the refusal says how long the agent has to send it: 600 seconds.

### Resources

> Ask: *"List my flows."* / *"Show me the NetSuite connection."* / *"Create an export that pulls Shopify orders."* / *"Disable the nightly sync."*

Every family has a `list_*` reader and an `upsert_*` writer, working on the resources you already know from integrator.io.

| Resource         | Tools                                            | What it is                                                                                                                                                                        |
| ---------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connections      | `list_connections` `upsert_connection`           | Credentials and config for one external system (NetSuite, Salesforce, an HTTP API, a database, SFTP). Shared by exports and imports.                                              |
| iClients         | `list_iclients` `upsert_iclient`                 | A reusable OAuth2 app registration (client id and secret) that connections use for OAuth.                                                                                         |
| Integrations     | `list_integrations` `upsert_integration`         | The top-level project that groups related flows, connections, and settings.                                                                                                       |
| Flows            | `list_flows` `upsert_flow` `patch_flow`          | A pipeline that moves data from a source export to a destination import, on a schedule or a trigger.                                                                              |
| Exports          | `list_exports` `upsert_export`                   | The source step that reads records out of a connection.                                                                                                                           |
| Imports          | `list_imports` `upsert_import`                   | The destination step that writes records into a connection.                                                                                                                       |
| AI Agents        | `list_ai_agents` `upsert_ai_agent`               | An LLM-powered import step that classifies, extracts, or generates data inside a flow.                                                                                            |
| Guardrails       | `list_guardrails` `upsert_guardrail`             | A safety check (PII detection, content moderation) that validates data moving through a flow.                                                                                     |
| Scripts          | `list_scripts` `upsert_script`                   | A JavaScript hook that transforms data or makes decisions during a flow run.                                                                                                      |
| APIs             | `list_apis` `upsert_api`                         | A custom HTTP endpoint you expose to external callers.                                                                                                                            |
| Tools            | `list_tools` `upsert_tool`                       | A reusable building block (lookup, import, transform) callable from flows, APIs, and agents.                                                                                      |
| MCP Servers      | `list_mcp_servers` `upsert_mcp_server`           | A customer-built MCP endpoint that exposes your Tools and APIs (the `mcpServers` resource, not this server).                                                                      |
| Lookup Caches    | `list_lookup_caches` `upsert_lookup_cache`       | An in-memory key-value store for fast lookups and deduplication during a flow run.                                                                                                |
| EDI Profiles     | `list_edi_profiles` `upsert_edi_profile`         | The interchange envelope for a trading partner (X12 ISA/GS or EDIFACT UNB): sender and receiver IDs, qualifiers, standards versions, control numbers. Required for B2B EDI flows. |
| File Definitions | `list_file_definitions` `upsert_file_definition` | Parsing and generation rules for structured files (CSV, fixed-width, X12, EDIFACT) that file-based exports and imports reference.                                                 |

**Good to know**

* **`list_*` does double duty.** No `_id` lists the collection (with `cursor` / `limit` to page and `include` / `exclude` to shape fields); an `_id` returns that one full resource. With an `_id`, `include` and `exclude` trim the fetched document, and the result carries a `_warning` that marks it partial. An `upsert_*` refuses a partial document as its body, because saving it would clear every field it leaves out. Without `limit`, a list drains the collection (up to 50 pages), so the agent narrows with a filter first. A `cursor` works only with the tool it came from; any other is refused with `Invalid pagination cursor`.
* **Filters differ by family.** Flows filter by `_integrationId`, `name`, `disabled`, `_abstractFlowId`, or open-error state (`hasOpenErrors`, `numError_gte`); APIs by `name` and `disabled`; Celigo Tools by `_integrationId`; and exports, imports, connections, and several other families by `externalId`. Exports, imports, and connections have no name or integration filter, so the agent lists them and matches client-side.
* **`upsert_*` with an `_id` is a full replace.** Read the resource first, change the fields you want, and send the whole document back, or omitted fields are cleared. The document can go back as read: fields the platform manages, such as `createdAt` and `lastModified`, are dropped and listed in `_strippedFields`, and any other field the write doesn't accept is refused by name.
* **Settings forms are checked before a save.** `upsert_flow`, `upsert_integration`, `upsert_export`, and `upsert_import` refuse a malformed `settingsForm`, such as a `fieldMap` placed beside `form` or a layout that names a field `fieldMap` doesn't define. The platform would store it as sent and show nothing for those fields.
* **`patch_flow` for single-field flow edits.** It applies JSON Patch `replace` operations to the platform's whitelist of flow paths — `/disabled`, `/name`, `/description`, `/schedule`, `/timezone`, and `/logging/debugUntil` among them — so the agent can enable a flow, change its schedule, or arm debug logging without the full-replace risk of `upsert_flow`. Send the whole cron string to `/schedule`: a pointer beneath it, such as `/schedule/cron`, is refused before the request, because the platform answers success and changes nothing. The debug window on `/logging/debugUntil` is capped by your license, and a later timestamp returns `422`. Other paths return `422 Unprocessable Entity`; change those fields with `upsert_flow`.
* **Integration Apps change through the app.** An Integration App is an integration with a `_connectorId`. `upsert_integration` refuses an update that changes or drops its `settings`, and `patch_flow` and `upsert_flow` refuse to switch one of its flows on or off, because a direct write skips the app's own code. Use `save_integration_app_settings` for both. See [Integration App settings](#integration-app-settings).
* **An update to a shared step waits for confirmation.** An update to an export, import, AI agent, or guardrail that two or more flows, Tools, or APIs use waits for your confirmation. See [Calls that wait for your confirmation](#calls-that-wait-for-your-confirmation).
* **Send credentials back as read.** Reads mask stored secrets on connections and iClients as `******`, and an update that sends the mask back keeps the stored secret on both. To rotate a secret, send its new value. On a connection, a secret left out of an object the body keeps (`http.auth.basic` without `password`) is re-sent for you and listed in `keptSecrets`, and a body that drops a whole object holding secrets, such as all of `http.auth` or the `netsuite` block, is refused. A mask at a path where nothing is stored is refused unless `force: true`, because the asterisks would be saved as the value. An iClient update refuses an omitted `oauth2.clientSecret` (422).
* **New flows start disabled.** Create flows with `disabled: true` and enable them only after the mappings and connections check out (`patch_flow` on `/disabled`).
* **A create can't set `sandbox`.** An `upsert_*` call with no `_id` refuses `body.sandbox: true`, because the platform would create a production resource instead. To build in another environment, connect to that environment: a session works in one.
* **AI agent and guardrail pages hold up to `limit`.** `list_ai_agents` and `list_guardrails` filter imports, and with `limit` or `cursor` they skip the pages that hold no match. A page comes back empty only when none are left, or with a `_note` when none turned up in the pages the call read.

### Run flows and inspect runs

> Ask: *"Run the daily inventory sync and tell me what happened."* / *"What is running right now?"* / *"Re-run yesterday's window for just the orders export."* / *"Show me what the orders export returns."*

| Tool                  | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_flow`            | write      | Trigger an immediate run; returns a `_jobId`. The flow must be enabled and belong to an enabled integration. An optional `body` targets the run: `export.startDate` / `export.endDate` override the delta window for backfills, and `_exportIds` runs only specific source exports.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `list_flow_runs`      | read       | Set `_id` to a parent job to get the parent plus per-step `children[]`, and add `includeFiles: true` to attach short-lived presigned download URLs for any files the run produced. Omit `_id` for run history: pass `_flowId` or `_integrationId` (`type` defaults to `flow`; `retry` and `bulk_retry` take the same scopes), or `type: "export"` / `"import"` with `_flowJobId` / `_parentJobId`. Returns 25 runs unless you set `limit`. A flow id passed as `_id` returns that flow's runs with a `_hint`.                                                                                                                                                                                                                                                                                                                                      |
| `run_export`          | read       | Run one saved export as a preview: read up to `limit` records (25 by default, 100 at most) from the live source and return them. Nothing is saved, no record is marked as exported, and no flow job is created. `limit` counts source records before the export's filter and hooks, so fewer can come back; `truncated: true` means the source may have more. Set `body.data` to one record only when the export's request uses `{{record.<field>}}`. A delta export also needs `lastExportDateTime` and `currentExportDateTime` in `body.data`, as ISO-8601 dates. `simple` and `webhook` exports are refused: the preview can't run those types.                                                                                                                                                                                                 |
| `list_current_jobs`   | read       | Jobs in flight right now — queued, running, or canceling. Optional `body` filters: `_flowIds` or `_integrationIds` (not both), `status`, and `applicationIds`. There is no time filter: to find long-running jobs, compare each job's `createdAt` or `startedAt`. Pass `nextCursor` back as `cursor` for the next page. Finished runs belong to `list_flow_runs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `cancel_flow_run`     | write      | Cancel a queued or running job mid-flight. Cancelling a parent flow job also cancels its child export and import jobs. A run that is already canceling or has finished is left alone: the call returns `changed: false` with its `status`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `list_execution_logs` | read       | Step-by-step logs for one run (`_id` flow + `_jobId`). Every logged run has them; the job's `logMode` (`basic`, `detailed`, or `debug`) sets how much they hold, and a debug run (`patch_flow` on `/logging/debugUntil`) adds the mapping, hook, and filter stages. Alone it returns one page of the log index as `{ logs, hasMore, nextCursor }`, filtered on the platform by `_stepId`, `status` (`success`, `error`, or `ignore`), and `traceKeyPrefix`, ordered with `sort`, and paged with `limit` (1,000 at most) and `cursor`; an empty first page comes back with a `_hint` on what to check. Add `_stepId`, `recordId`, and `groupId` for one record's step timeline; add `stage` — `apiCall`, `mapping`, or a hook's `<hook>Hook` stage such as `preMapHook` — for the payloads at that stage. An unknown stage returns an empty result. |
| `create_event_report` | write      | Queue a report of flow events: `{ type: "flow_events", _flowIds, startTime, endTime? }`. `startTime` must be within the last 30 days and the window at most 3 days long, or the call returns `422`. Generation takes minutes, there is no delete, and a report expires after 30 days.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `list_event_reports`  | read       | Event reports, newest first, filtered by `_flowId` or `status` (`queued`, `running`, `completed`, or `canceled`); or one report with `_id`. A list returns 25 reports unless you set `limit` (100 at most), with a `total`; pass `nextCursor` back as `cursor` for the next page. A `completed` report read by `_id` includes `downloadURL`, a gzip-encoded CSV that stays valid about 15 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Triage errors

> Ask: *"Where are the errors across my account?"* / *"Show the open errors on that import, then retry the timeouts."*

Start wide, then drill in: `list_flow_errors` with no arguments returns the per-flow open-error rollup — every flow with open errors and its count, sorted by count, 100 flows per page (follow `nextCursor` when `hasMore` is `true`). `totalErrors` and `affectedFlows` cover every page, not only the one returned. Add `_integrationId` to keep it to one integration. `list_flows` with `hasOpenErrors: true` (or `includeErrorCounts: true`) returns the same counts on the flow documents.

| Tool                           | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_flow_errors`             | read       | Errors at any scope, including lookup steps and steps inside router branches. No arguments: the per-flow rollup, one row per flow with `numOpenError` and `lastErrorAt` (`numError_gte: 0` lists every flow in scope). `_id`: one flow's errors grouped by step. `_id` + `_stepId`: one step's full error objects — `errorId`, `message`, `code`, `traceKey`, `retryDataKey`, `occurredAt`. With a flow or step, `status: "resolved"` returns the errors already closed, by a user or by the platform (`resolvedBy: "auto"`), and filters narrow either list: `_flowJobId`, `occurredAt_gte` / `occurredAt_lte`, `tags`, and for resolved errors `resolvedAt_gte` / `resolvedAt_lte` and `resolvedBy`. `_flowJobId` needs `occurredAt_gte` with it, or `resolvedAt_gte` for resolved errors, and `tags` takes `tagId` codes from `list_tags` or `untagged`, not tag names. Without a flow or step, `status: "resolved"` and these filters are refused; `summary: false` returns the full error objects of every flow in scope, grouped by flow and step, which is one request per step. |
| `get_flow_error_request`       | read       | The HTTP request and response stored with one error, by the error's `reqAndResKey`: the method, URL, headers, and body sent, and the status, headers, and body that came back. Credentials are masked before storage. Steps that make no HTTP call have no `reqAndResKey`. `includeFileUrl: true` adds `fileSignedURL`, a short-lived URL for a body too large to store with the error; when the bodies are stored inline it is `null`, and `fileNote` says so.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get_flow_error_retry_data`    | read       | The stored retry snapshot for one error (`retryDataKey`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `update_flow_error_retry_data` | write      | Full-replace that snapshot to fix a staged payload before retrying. Does not reprocess. A body with an empty or missing `data` is refused, because it would wipe the record.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `triage_flow_errors`           | write      | One action on a step's errors: `retry` (writes to destinations), `resolve`, `tag` (codes from `list_tags`), or `assign` (by email). `tag` replaces each listed error's tags with `tagIds`, three at most, and `[]` clears them; to add a tag, send the error's current codes plus the new one. Set `retryAll` or `resolveAll` to act on every error open on the step when you call it, without listing ids.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `list_tags`                    | read       | Error tags in the account as `{ items, hasMore }`; use each `tagId` short code with `triage_flow_errors`. If `hasMore` is `true`, call again with a higher `limit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Lookup cache data

> Ask: *"What is cached under the customer-xref keys?"*

| Tool                       | Read/Write | Description                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_lookup_cache_data`   | read       | Read entries. Filter with `key`, `keys`, or `startsWith`; omit all for the first page (about 1000 entries).                                                                                                                                                                                                                  |
| `upsert_lookup_cache_data` | write      | Load or replace entries (`body: { data: [{ key, value }] }`). Auto-batches in groups of 1000.                                                                                                                                                                                                                                |
| `delete_lookup_cache_data` | write      | Remove entries by `key` / `keys`, or set `all: true` to purge every entry (the cache resource stays). Omitting keys without `all: true` is rejected. A purge can't be undone: the entries come back only if they're reloaded from their source, so it [waits for your confirmation](#calls-that-wait-for-your-confirmation). |

### B2B EDI transactions

> Ask: *"Did the 850s from Acme land yesterday, and were any acknowledgments rejected?"*

The transaction log for [B2B Manager](https://docs.celigo.com/hc/en-us/articles/28037678084123-Getting-started-with-EDI-B2B-Manager) EDI exchange. The EDI *building blocks* — profiles and file definitions — are regular resources in the table above; these two tools cover the runtime side.

| Tool                    | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_edi_transactions` | read       | Query the EDI transaction log. Filter by `fileType` (`X12`, the default, or `EDIFACT`), `documentType` (a document code like `"850"` or `"ORDERS"`; the family names `X12` and `EDIFACT` are refused), `direction`, `documentNumber`, `_integrationId`, and a date window; or set `_id` for one transaction. The server applies `direction`, `documentType`, and `_integrationId` to each fetched page, so a filtered page can hold fewer rows than `limit` while `hasMore` is `true`. `includeFaDetails` / `includeMdn` fetch acknowledgment detail per returned row — an extra API call each, so keep `limit` small when you use them; FA details exist only for transactions whose `faStatus` is `rejected`. With `_id`, `includeFiles: true` adds `ediFileSignedURL`, a download URL for the raw EDI file that expires in about 15 minutes. `includeContent: true` attaches the X12 or EDIFACT text itself as `ediContent`: it needs `_id` or the `documentNumber` filter, covers at most 10 transactions per call, and cuts files over 256 KB. |
| `update_edi_fa_status`  | write      | Set functional-acknowledgment status on a batch of transactions. Only `accepted` and `rejected` are writable; other statuses are system-managed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### Marketplace templates

> Ask: *"Install the Shopify to NetSuite template and wire it to my existing connections."*

| Tool               | Read/Write | Description                                                                                                                                                                                                                                                                                             |
| ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_marketplace` | read       | Browse the published marketplace catalog (templates by default, sorted by installs), or set `_id` to preview one template's full blueprint — every resource the install would create. The preview doubles as a source of working example configs while building.                                        |
| `install_template` | write      | Install a template into a new integration. Requires a `connectionMap` pairing each connection in the template's preview with a real connection `_id` in your account. Every call installs another copy, so after a timeout, look for the new integration with `list_integrations` before calling again. |

### Integration App settings

> Ask: *"Show the settings on my Shopify - NetSuite Integration App."* / *"Turn on its fulfillment flow."*

An Integration App is an integration installed from the marketplace that carries a `_connectorId`. Its settings are saved through the app's own code, as the **Save** button on its settings page does, so use these two tools for that work, not `upsert_integration` or `patch_flow`.

| Tool                            | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_integration_app_settings` | read       | Every settings field of one Integration App as a flat list, with the value each holds and the shape `save_integration_app_settings` takes. Narrow with `name` (matches a field's name or label) or, for a multi-store app, `store`. An integration with no `_connectorId` is refused: its settings are plain fields, saved with `upsert_integration`.                                                 |
| `save_integration_app_settings` | write      | Save `values` (field name to value, with names from `list_integration_app_settings`), or switch one of the app's flows on or off with `flow: { _id, disabled }`. Every name is checked against the form before the request. The integration is read back afterward and each field is reported `saved`, `unchanged`, or `not-saved`, because the platform answers success even when it stored nothing. |

### Celigo Storage files

> Ask: *"Upload this price list CSV to storage."* / *"Find the invoice PDF and give me a download link."*

Managed file and folder storage on your account. Deletes are soft: a deleted item sits in the recycle bin for 30 days before it purges, and `restore_storage_item` brings it back.

| Tool                            | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_storage_items`            | read       | Browse one folder's children (`_parentId`, with a `breadcrumb` of the path), search names account-wide (`search`), or list the recycle bin (`deleted: true`). A search matches an item when any word of its name starts with any word of the query, ignoring case, so it is not an exact or substring match: check each hit's `name`. Filter by `type`, `mimeType`, or a modified-date window. A `_parentId` that isn't a folder returns a `404` error that names it. |
| `upsert_storage_item`           | write      | Create folders and files, rename, move, edit descriptions, or replace file content. Send text as `content` or binary as `contentBase64` (inline cap 4 MB by default), or use `presignedUpload` to stream larger files from disk without routing bytes through the agent.                                                                                                                                                                                              |
| `get_storage_file_download_url` | read       | A presigned URL for one file's content; fetch it with a plain HTTP `GET`. `expiresIn` says how many seconds the URL stays valid, which is 24 hours in production. Anyone holding the URL can use it until then, so treat it as a credential. `includeContent: true` returns the file's text as `content` instead, for text files up to 1 MB, cut at 256,000 characters; a binary or larger file returns the URL with a `_warning`.                                    |
| `restore_storage_item`          | write      | Bring a soft-deleted item back from the recycle bin to its original location. Restoring a folder also restores what was deleted with it. Items stay recoverable for 30 days. If a live item has taken the name since the delete, the restore is refused with `409` and the item stays in the bin.                                                                                                                                                                     |
| `cancel_storage_upload`         | write      | Abort an abandoned multipart create upload and release its reserved quota. Never cancel a replacement upload — the platform may delete the existing file instead of restoring its previous content.                                                                                                                                                                                                                                                                   |

Deleting goes through `delete_resource` with `resourceType: "storage-items"` — a soft delete into the recycle bin, reversible with `restore_storage_item`. The dependency pre-flight reports nothing for storage items, so check what uses a file, such as an MCP server's resources or a flow step that reads its folder, before deleting it.

### Account and utilities

> Ask: *"Who changed the order flow last week?"* / *"Invite Dana to the account as a monitor."*

| Tool                     | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_environments`      | read       | Every environment on the account, including Production. Accounts without multiple environments get an empty list, not an error.                                                                                                                                                                                                                                                                                  |
| `list_users`             | read       | Everyone in the account — the owner plus invited users — with `accessLevel`, per-integration grants, `status`, the `accountMFARequired` and `accountSSORequired` sign-in requirements, and the `_ashareId` handle that `manage_user` needs. Requires owner or administrator access.                                                                                                                              |
| `manage_user`            | write      | One user-management action per call: `invite` (by `email`), `update_permissions`, `disable`, or `enable` (by `_ashareId` from `list_users`). `update_permissions` replaces the user's integration grants, so send every grant to keep, and it keeps the user's MFA requirement unless the body sets `accountMFARequired`. Admin-only, and the owner cannot be managed.                                           |
| `list_audit_log_entries` | read       | Audit log, newest first, with `fieldChanges[]`. Filter by `resourceType`, `_resourceId`, `_byUserId`, `action`, `source` (including `mcp` and `cli`), and date range. With `resourceType` and `_resourceId`, the entries also cover the resource's descendants — a flow's steps and their connections and scripts, an integration's flows — unless you set `includeDescendants: false` or filter by `fieldPath`. |
| `delete_resource`        | write      | Delete by `resourceType` and `_id` across all resource families. Returns `{ deleted, id, warnings, response }`. A best-effort dependency pre-flight lists dependents in `warnings[]` for every type except `storage-items`, which never reports any. Warnings never block the delete. Deleting an iClient [waits for your confirmation](#calls-that-wait-for-your-confirmation).                                 |
| `submit_feedback`        | write      | File structured feedback about a tool — a wrong schema, a misleading description, a missing capability — with Celigo, so the agent can report problems as it finds them. `dry_run: true` validates the report without filing it.                                                                                                                                                                                 |

### Schema and knowledge

> Ask: *"What fields does a NetSuite connection need?"* / *"How do delta exports work?"* / *"Use the Celigo skill for mappings."*

| Tool          | Read/Write | Description                                                                                                                                                                                                                                                                                                    |
| ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_schema`  | read       | Fetch resource and connector schemas on demand. See [Fetching schemas on demand](#fetching-schemas-on-demand-with-get_schema) above.                                                                                                                                                                           |
| `get_skill`   | read       | Read a Celigo skill. No `name` lists the skills; `name` returns that skill's `SKILL.md` and its file list, and `path` returns another of its files, such as `references/mcp.md`. A name that doesn't exist returns the valid names. See [Skills](#skills) below.                                               |
| `search_docs` | read       | Ask a natural-language question and get an answer from the Celigo Knowledge Base, with links to the source articles. Set `context_aware: true` with a `url` for an answer about a specific integrator.io page. Each call is answered on its own unless you pass a `thread_id` that an earlier answer returned. |

***

## Beyond tools: skills, prompts, and resources

Alongside its tools, the server serves Celigo's skills, guided prompts, and reference resources. All three are open-sourced in [`celigo/ai`](https://github.com/celigo/ai) and loaded by the server, so the catalog stays in sync with the skills, prompts, and reference material.

**How your client surfaces these.** Tools are model-controlled — every client hands them to the agent automatically. Prompts and resources are *user*-controlled, so clients expose them as explicit affordances rather than agent tools, and where they appear differs by client:

* **Claude Code** — run `/mcp` to browse them; invoke a prompt as a slash command (`/mcp__celigo__plan-new-integration`); attach a resource with an `@` mention.
* **Claude Desktop** — add them from the **+** (add context) menu.
* **Cursor** — tools, prompts, and resources appear together in the MCP settings panel.

If a client only shows the tool list, the prompts and resources aren't missing — they're reached through these user actions, and the agent can still read any skill with `get_skill`.

### Skills

Skills are Celigo's step-by-step guides for building, changing, and troubleshooting integrations, one per kind of task: `building-flows`, `configuring-connections`, `writing-mappings`, `troubleshooting-flows`, and so on. They are the same skills the Celigo CLI installs for coding assistants (see [AI assistant skills](https://developer.celigo.com/cli/using-the-cli/skills)). The agent reads the matching skill before it builds, changes, or diagnoses something. The server's instructions name every skill it serves, so the agent asks for one that exists.

The server offers the skills three ways, so every client can use them:

* **`get_skill`.** A read-only tool, for clients whose agents only call tools. See [Schema and knowledge](#schema-and-knowledge) above.
* **Resources.** Each skill's `SKILL.md` is listed as a resource at `skill://celigo/<name>/SKILL.md`, and its other files are readable at `skill://celigo/<name>/<path>`, so you can attach a skill like any other resource.
* **The MCP Skills extension.** The server declares the `io.modelcontextprotocol/skills` extension. A client that supports it lists the skills with `skills/list`, each with its frontmatter and files, and reads one with `skills/get`.

### Guided prompts

Multi-step playbooks your client can invoke directly — in Claude Code and Claude Desktop they show up as slash commands. Each one composes the tools above into a workflow.

| Prompt                 | What it guides                                                                           | Arguments                                |
| ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------- |
| `getting-started`      | Orient in an account: core concepts, build order, and which prompt to use next.          | —                                        |
| `audit-account-health` | Count resources, find erroring flows and offline connections, return a prioritized list. | —                                        |
| `troubleshoot-flow`    | Diagnose a failing flow from its latest job and step errors.                             | `flowId` (optional)                      |
| `diagnose-connection`  | Diagnose a failing or offline connection.                                                | `connectionId` (optional)                |
| `review-flow-config`   | Review a flow's mappings, connections, and steps for problems.                           | `flowId` (optional)                      |
| `plan-new-integration` | Plan a new integration between two applications.                                         | `sourceApp`, `destinationApp` (optional) |
| `writing-handlebars`   | Author Handlebars expressions for mappings, HTTP bodies, SQL, URIs, and filters.         | —                                        |
| `writing-sql`          | Author SQL for RDBMS exports and imports.                                                | —                                        |

### Reference resources

Static context the agent reads on demand, under the `celigo://resources/...` URI scheme. Each skill's `SKILL.md` is listed alongside them, under `skill://celigo/...`.

| Resource                   | Content                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Product glossary           | Official Celigo terminology and definitions.                                                                            |
| Tool usage guide           | How to approach common tasks and which tools to chain.                                                                  |
| Error pattern reference    | Common error codes, their causes, and typical resolutions.                                                              |
| Connector catalog          | Supported connection types, HTTP connectors, trading-partner connectors, and templates.                                 |
| API reference              | Overview of the REST API by resource, linking to the full OpenAPI spec.                                                 |
| Account architecture model | How to read an account as a dependency graph: resource hierarchy, blast radius, and risk.                               |
| Account settings reference | Account-level and personal settings: subscription entitlements versus usage, audit log, data retention, and MFA policy. |
| Handlebars helper catalog  | Every custom Handlebars helper — inline, block, and data variables — with signatures and examples.                      |
| Recycle bin reference      | The 30-day soft-delete lifecycle: what the recycle bin holds, cascade restore, and purge.                               |

Connector and resource *schemas* are not resources — fetch those with the `get_schema` tool.


---

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

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.celigo.com/mcp/tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
