> 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 — 29 tools. 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 Six **verb tools** cover every resource family. Each takes a `resourceType` that names the family, and the tool's own description tells the agent which filters and notes apply to each one: | Verb tool | What it does | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_resources` | List a collection. `resourceType` plus optional filters; `limit` / `cursor` to page; `include` / `exclude` to shape fields. Without `limit` it drains the collection (up to 50 pages), so the agent narrows with a filter first. | | `get_resource` | One resource by `_id`, or — with `schema: true` — the family's JSON schema with guidance, so the agent learns the fields before it writes. | | `create_resource` | Create (POST). The server assigns the id. | | `update_resource` | Full-document replace (PUT). Read the resource first, change the fields you want, write the whole document back — omitted fields are cleared. | | `patch_resource` | Change a few fields with JSON Patch on a whitelist of paths per family — enable or disable a flow, rename, change a schedule, arm debug logging, set connection concurrency — without the full-replace risk. | | `delete_resource` | Delete by `_id`. A best-effort dependency pre-flight returns any dependents as advisory `warnings[]`, but the delete always proceeds — it never blocks. | `resourceType` values: `integrations`, `flows`, `connections`, `exports`, `imports`, `ai-agents`, `guardrails`, `scripts`, `apis`, `tools`, `mcp-servers`, `iclients`, `lookup-caches`, `tags`, `environments` (read-only), `edi-profiles`, `file-definitions`, and the read-only `http-connectors` catalog; `delete_resource` also takes `storage-items`. The other 23 tools are operations that do not fit CRUD: running flows and inspecting runs, error triage, execution logs, lookup-cache data, EDI transactions, the marketplace, Celigo Storage files, users, schemas, Knowledge Base search, and feedback. They are all in the catalog below. Why this shape: one verb per action across all families keeps the catalog small — 29 tools instead of one pair per resource — 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, and a filter the chosen family does not support is rejected before any API call, with the supported list, so the agent recovers in one turn. Every tool also declares standard [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) (read-only, destructive, idempotent), so clients that understand them badge reads and writes correctly and can ask for confirmation before destructive calls. On clients that support MCP elicitation, the server asks for an explicit confirmation before a write that would wipe stored credentials or retry every error on a step. > **Older tool names.** Before version 0.12.0 the catalog had one `list_` and one `upsert_` tool per resource (`list_flows`, `upsert_connection`, …), and older releases used `get_flow`, `list_jobs`, `deploy_template` and similar names. All of them still work: the server rewrites an old name onto the current tool with the right arguments, so a client holding a cached tool list is not broken — but they are not listed, and new work should use the names on this page. ### Learning fields before writing Resource and connector schemas are large, so they are not bundled into `tools/list`. The agent pulls only what it needs, when it needs it: * `get_resource` with `schema: true` returns the family's schema (`resourceType: "connections"`, `adaptorType: "netsuite"` for an adaptor-specific shape) together with the family's guidance and write notes. * `list_resources` / `get_resource` with `resourceType: "http-connectors"` browse the HTTP connector catalog (`search` by name; `includeOpenApi` for a connector's OpenAPI fragment), and `get_resource` on a connection with `includeMetadata: true` returns native application metadata — record types and fields for a NetSuite, Salesforce or database connection. * `get_schema` remains as a shortcut with the same content (`target: "resource" | "connector" | "connector_openapi"`). A good build loop is: learn the fields, construct the body, then `create_resource`. 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 `get_resource` for the flow, sees the export and import references in the response, then calls `get_resource` for each export and import 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_*`, and `search_docs` are **reads**. Everything else — `create_resource`, `update_resource`, `patch_resource`, `delete_resource`, `run_flow`, `cancel_flow_run`, the error-triage writers, `update_edi_fa_status`, `install_template`, `manage_user`, the lookup-cache-data and storage writers, and `submit_feedback` — **changes live data**, so a careful agent confirms before calling them. > ⚠️ **Writes act on your real account, and `delete_resource` never blocks.** The write tools 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. Confirm the agent's plan before any write. ### Resources > Ask: *"List my flows."* / *"Show me the NetSuite connection."* / *"Create an export that pulls Shopify orders."* / *"Disable the nightly sync."* Every family below is reached through the six verb tools with its `resourceType`. | `resourceType` | What it is | Verbs and filters | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connections` | Credentials and config for one external system (NetSuite, Salesforce, an HTTP API, a database, SFTP). Shared by exports and imports. | list (`externalId`, `fetchQueueSize`), get (`includeMetadata`), create, update, patch (`/name`, `/offline`, concurrency, debug window), delete | | `iclients` | A reusable OAuth2 app registration (client id and secret) that connections use for OAuth. | list, get, create, update, delete | | `integrations` | The top-level project that groups related flows, connections, and settings. | list, get, create, update, patch (`/name`, `/description`, `/settings`), delete | | `flows` | A pipeline that moves data from a source export to a destination import, on a schedule or a trigger. | list (`_integrationId`, `name`, `disabled`, `sort_by`, `includeInstances`, `_abstractFlowId`), get, create, update, patch (`/disabled`, `/name`, `/description`, `/schedule/*`, `/logging/*`), delete | | `exports` | The source step that reads records out of a connection. | list (`externalId`), get, create, update, delete | | `imports` | The destination step that writes records into a connection. | list (`externalId`), get, create, update, delete | | `ai-agents` | An LLM-powered import step that classifies, extracts, or generates data inside a flow. | list, get, create, update, delete | | `guardrails` | A safety check (PII detection, content moderation) that validates data moving through a flow. | list, get, create, update, delete | | `scripts` | A JavaScript hook that transforms data or makes decisions during a flow run. | list, get, create, update, patch (`/name`, `/description`, `/content`), delete | | `apis` | A custom HTTP endpoint you expose to external callers. | list (`name`, `disabled`), get, create, update, patch, delete | | `tools` | A reusable building block (lookup, import, transform) callable from flows, APIs, and agents. | list (`_integrationId`, `publishedOnly`), get, create, update, patch, delete | | `mcp-servers` | A customer-built MCP endpoint that exposes your Tools and APIs (the `mcpServers` resource, not this server). | list, get, create, update, patch, delete | | `lookup-caches` | An in-memory key-value store for fast lookups and deduplication during a flow run. Entries are managed by the lookup-cache-data tools below. | list, get, create, update, delete | | `tags` | Error tags; each `tagId` short code is what `triage_flow_errors` applies. | list, get, create, update, patch (`/tag`), delete | | `environments` | Every environment on the account, including Production. Accounts without multiple environments get an empty list, not an error. | list, get | | `edi-profiles` | 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. | list, get, create, update, delete | | `file-definitions` | Parsing and generation rules for structured files (CSV, fixed-width, X12, EDIFACT) that file-based exports and imports reference. | list, get, create, update, delete | | `http-connectors` | The catalog of pre-built HTTP connectors (auth, endpoints, pagination). | list (`search`), get (`includeOpenApi`) | **Good to know** * **Filters are per family.** Every family accepts `limit`, `cursor`, `include`, `exclude`; the type-specific filters are listed in the `list_resources` description and enforced — an unsupported filter is rejected with the supported list. There is no name or integration filter on exports, imports or connections (`externalId` only); the agent lists and matches client-side. `_integrationId` narrows flows, Celigo Tools and syncs. * **`update_resource` is a full replace.** Read the resource first, change the fields you want, and send the whole document back, or omitted fields are cleared. Prefer `patch_resource` for one or two fields. * **`patch_resource` paths are whitelisted per family.** The tool description carries the complete table. Unlisted paths are rejected before any API call. * **Credentials never round-trip.** Reads mask secrets on connections and iClients as `******`. A connection update that still contains the mask would wipe the stored secret, so the server blocks it — or, on clients that support elicitation, asks you to confirm. iClient updates treat the mask as keep-the-current-secret. * **New flows start disabled.** Create flows with `disabled: true` and enable them only after the mappings and connections check out (`patch_resource` on `/disabled`). * **Empty lists on a scoped token.** If a list is empty on an account that clearly has resources, the API token is probably scoped to specific integrations — list flows with `_integrationId` (the integration filter exists on flows, Celigo Tools and syncs; connections, exports and imports have none — list them and match client-side). ### 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."* | 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 | Flow runs (jobs). Set `_id` to a parent job to get the parent plus per-step `children[]` (add `includeFiles: true` for short-lived presigned download URLs of any files the run produced). Omit `_id` for run history scoped by `_flowId` or `_integrationId`, or set `current: true` for the runs in flight right now — queued, running, or canceling. | | `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. | | `list_execution_logs` | read | Step-by-step debug logs for one run (`_id` flow + `_jobId`; the flow needs debug logging armed — `patch_resource` on `/logging/debugUntil`). Alone it returns the log index, filterable by `status`, `traceKeyPrefix` and `_expOrImpId`; add `_stepId`, `recordId`, and `groupId` for one record's step timeline; add `stage` for the actual request and response payloads at that stage. | ### Triage errors > Ask: *"Where are the errors across my account?"* / *"Show the open errors on that import, then retry the timeouts."* / *"What got resolved last week?"* Start wide, then drill in: `list_flow_errors` with no arguments returns one row per flow with its open-error count, worst first (scope with `_integrationId`; `numError_gte: 0` includes flows with zero errors). Then narrow to a flow and a step. | Tool | Read/Write | Description | | ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_flow_errors` | read | Errors at any scope. No arguments: every flow with open errors and its count. `_id`: one flow's errors grouped by step. `_id` + `_stepId`: one step's full error objects — `errorId`, `message`, `code`, `traceKey`, `retryDataKey`, `occurredAt`. `status: "resolved"` returns resolved history instead (who resolved it, when; `resolvedBy: "auto"` marks transient errors cleared by auto-retry). Filters: `_flowJobId`, `occurredAt_gte` / `_lte`, `tags`, and for resolved errors `resolvedAt_gte` / `_lte`, `resolvedBy`. | | `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. | | `triage_flow_errors` | write | One action on a step's errors: `retry` (writes to destinations), `resolve`, `tag` (codes from `list_resources` with `resourceType: "tags"`), or `assign` (by email). Set `retryAll` or `resolveAll` to act on every open error for the step without listing ids; clients that support elicitation get a confirmation prompt first. | ### Lookup cache data > Ask: *"What is cached under the customer-xref keys?"* | Tool | Read/Write | Description | | -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_lookup_cache_data` | read | Read entries of a cache (`_id` from `list_resources` with `resourceType: "lookup-caches"`). Filter with `keys` or `startsWith`; omit both 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 `keys`, or set `all: true` to purge every entry (the cache resource stays). Omitting keys without `all: true` is rejected. | ### 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"` — not the family name), `direction`, `documentNumber`, `_integrationId`, and a date window; or set `_id` for one transaction. `includeFaDetails` / `includeMdn` fetch acknowledgment detail per returned row — an extra API call each, so keep `limit` small when you use them; `includeFiles` attaches short-lived download URLs. | | `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. | ### 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 `upsert_storage_item` with `restore: true` 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`, case-insensitive substring), list the recycle bin (`deleted: true`), or set `_id` for one item — add `includeDownloadUrl: true` for a short-lived presigned URL to its content (anyone holding the URL can use it until it expires, so consume it promptly). Filter by `type`, `mimeType`, `_integrationId`, or a modified-date window. | | `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 (`stage: "cancel"` aborts an abandoned upload). `restore: true` brings a soft-deleted item back to its original location; restoring a folder also restores what was deleted with it. | Deleting goes through `delete_resource` with `resourceType: "storage-items"` — a soft delete into the recycle bin, reversible for 30 days. ### Account and utilities > Ask: *"Who changed the order flow last week?"* / *"Invite Dana to the account as a monitor."* | Tool | Read/Write | Description | | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_users` | read | Account users of one kind (`userType` is required): the owner plus invited users with `accessLevel`, per-integration grants, `status`, and the `_ashareId` handle that `manage_user` needs; or end users of your MCP servers and APIs. Requires owner or administrator access for account users. | | `manage_user` | write | One user-management action per call on the population selected by `userType`: `invite` (by `email`), `update_permissions`, `disable`, `enable`, or `revoke` (by `_ashareId` from `list_users`). 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. | | `submit_feedback` | write | File structured feedback about a tool — a wrong schema, a misleading description, a missing capability — so the agent can report problems back to Celigo. | ### Schema and knowledge > Ask: *"What fields does a NetSuite connection need?"* / *"How do delta exports work?"* | Tool | Read/Write | Description | | ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_schema` | read | Fetch resource and connector schemas on demand — the same content as `get_resource` with `schema: true` and the `http-connectors` family. See [Learning fields before writing](#learning-fields-before-writing) above. | | `search_docs` | read | Ask a natural-language question and get an answer from the Celigo Knowledge Base. Supports follow-ups via `thread_id` and location-aware answers via `url`. | *** ## Beyond tools: prompts and resources The server exposes two more MCP primitives alongside its tools. Both are open-sourced in [`celigo/ai`](https://github.com/celigo/ai) and loaded by the server, so the catalog stays in sync with the 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** — all three 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. ### 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. | 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 `get_resource` (`schema: true`) or the `get_schema` tool.