> 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 — it never blocks.

A few operation tools sit outside the pattern: `run_flow` and `patch_flow`, the job inspectors (`list_jobs`, `list_current_jobs`, `cancel_job`), the error-triage tools, the execution-log reader, the lookup-cache-data tools, the EDI transaction tools, the marketplace pair, the user-management pair, the Celigo Storage file tools, `get_schema`, and `search_knowledge_base`. 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 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.

### 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`.
* `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.
* `target: "connector_openapi"` returns the OpenAPI fragment for an HTTP connector's REST surface.

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_*`, and `search_knowledge_base` are **reads**. Everything else — the `upsert_*` writers, `patch_flow`, `delete_resource`, `run_flow`, `cancel_job`, the error-triage writers, `update_edi_fa_status`, `deploy_template`, `manage_user`, and the storage writers — **changes live data**, so a careful agent confirms before calling them.

> ⚠️ **Writes act on your real account, and `delete_resource` never blocks.** `upsert_*`, `run_flow`, `triage_flow_errors`, `deploy_template`, `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. 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."*

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. A few add filters: flows by `_integrationId`, `_abstractFlowId`, or open-error state (`hasOpenErrors`, `numError_gte`), tools by `_integrationId`, and most resources by `externalId`.
* **`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.
* **`patch_flow` for single-field flow edits.** It applies JSON Patch `replace` operations to a whitelist of paths — `/disabled`, `/name`, `/description`, `/schedule/*`, `/logging/*` — so the agent can enable a flow or arm debug logging without the full-replace risk of `upsert_flow`. Unlisted paths return `422 Unprocessable Entity`.
* **Credentials never round-trip.** Reads mask secrets on connections and iClients as `******`, and writing the mask back is handled per type. `upsert_connection` rejects a payload that still contains the mask unless you pass `force: true`, so a re-sent read cannot wipe a stored secret. `upsert_iclient` treats the mask as keep-the-current-secret, so resending it (or omitting the field) preserves what is stored.
* **New flows start disabled.** Create flows with `disabled: true` and enable them only after the mappings and connections check out.

### Run flows and inspect jobs

> Ask: *"Run the daily inventory sync and tell me what happened."* / *"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_jobs`           | read       | Omit `_id` to list finished jobs — list mode requires `type`, plus `_integrationId` or `_flowId` for `flow` / `retry` / `bulk_retry` jobs, or `_flowJobId` / `_parentJobId` for `export` / `import` jobs. 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. |
| `list_current_jobs`   | read       | Jobs in flight right now — queued, running, or canceling. Optional `body` filters: `_flowIds`, `_integrationIds`, `status`, and a time window. Finished jobs belong to `list_jobs`.                                                                                                                                                                                                          |
| `cancel_job`          | 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). Alone it returns the log index; 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."*

Start wide, then drill in: `list_flow_errors` with no arguments returns an account-wide summary of every erroring flow and step, scanning up to 100 flows per call (follow `nextCursor` when `hasMore` is `true`). `list_flows` with `hasOpenErrors: true` (or `includeErrorCounts: true`) surfaces the flows that need attention, sorted by open-error count.

| Tool                           | Read/Write | Description                                                                                                                                                                                                                                                                  |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_flow_errors`             | read       | Open errors at any scope. No arguments: account-wide summary (`totalErrors`, affected flows and steps). `_id`: one flow's errors grouped by step. `_id` + `_stepId`: one step's full error objects — `errorId`, `message`, `code`, `traceKey`, `retryDataKey`, `occurredAt`. |
| `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_tags`), or `assign` (by email). Set `retryAll` or `resolveAll` to act on every open error for the step without listing ids.                                              |
| `list_tags`                    | read       | Error tags in the account; use each `tagId` short code with `triage_flow_errors`.                                                                                                                                                                                            |

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

### 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. |
| `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. |
| `deploy_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 `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`, case-insensitive substring), or list the recycle bin (`deleted: true`). Filter by `type`, `mimeType`, 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. |
| `get_storage_file_download_url` | read       | A short-lived presigned URL for one file's content; fetch it with a plain HTTP `GET`. Anyone holding the URL can use it until it expires, so consume it promptly.                                                                                                        |
| `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.                                                                                             |
| `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`.

### 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`, 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`). 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`, and date range.                                                                                             |
| `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. Warnings never block the delete. |

### 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. See [Fetching schemas on demand](#fetching-schemas-on-demand-with-get_schema) above.                        |
| `search_knowledge_base` | 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 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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.