pipefy-ipaas

iPaaS (Advanced Automations)

MCP clients: read references/mcp.md. CLI users: read references/cli.md. Examples below describe shared operation arguments.

Pipefy's embedded workflow-automation platform. A flow is a trigger plus a sequence of steps that call pieces (integration connectors). The flow-builder verbs are catalog entries you discover per pipe and invoke through call_ipaas_tool, never a fixed operation list.

When to use

• "Integrate with Slack / Gmail / Google Sheets / an external app."
• User asks to integrate Pipefy with an external app (Slack, Gmail, Sheets, etc.) — use iPaaS tools here, not traditional automations or AI agents by default.
• "When a webhook comes in, do X." "On a schedule, do Y."
• "Build a multi-step flow with a router / loop / code step."
• Managing iPaaS data tables (separate from Pipefy database tables).

When not to use: native if/then rules on card events, or prompt-driven AI automations, both live in pipefy-automations. Simple HTTP callbacks on card events are create_webhook in pipefy-members-email-webhooks.

Prerequisites

• iPaaS enabled on the organization. If not, the backend typically returns a permission error (often coded PERMISSION_DENIED with text like "iPaaS is disabled for your organization" — exact code/string is backend-dependent).

• Permission to create automations on the pipe (pipe-admin ability).
• Service account must be a pipe member. When a flow runs under a service account, that account must be a member of the target pipe, or pipe-scoped calls under its identity fail with a permission error even after the flow is built. Adding the account elsewhere (org-level) is not enough. Provision one with create_service_account if needed, then attach it with add_service_account_to_pipe(pipe_id, email, role_name) immediately — see pipefy-members-email-webhooks and docs/mcp/tools/service-accounts.md. The catalog operations act as the calling session's identity, so this applies to the service account your flow runs under, not to the catalog caller.

• The iPaaS workspace is per-pipe: the catalog and any existing flows, connections, and tables belong to one pipe_id, so the same call against two pipes can differ.

Operations

Discover the operation catalog

The catalog is large (flow building, testing, tables, runs), some entries carrying very large input schemas. Do not load them all. Work in three steps:

1. get_ipaas_tools(pipe_id) — compact catalog: each entry's name and one-line description.
2. get_ipaas_tools(pipe_id, tool_name="...") — one entry's full description and inputSchema, fetched right before you use it.
3. call_ipaas_tool(pipe_id, tool_name="...", arguments={...}) — invoke it. Arguments are forwarded verbatim; the iPaaS host validates them and its error messages relay back.

Never expand more than the entry you are about to call, and read the entry's own schema for exact argument names (they are not uniform across the catalog). What the catalog offers, by capability group:

• Author a flow — create a flow (trigger plus steps) in one call; add or update individual steps; set or update the trigger; add conditional router branches; rename or duplicate a flow. Steps can be an integration piece, a code step, a loop, or a router (prefer a piece over code).
• Inspect a flow — list flows; read a flow's step tree and per-step validity; validate a flow before publishing.
• Discover pieces — search the piece catalog (exact or fuzzy); read a piece action/trigger's input properties; resolve dropdown option values; validate a step config before applying it.
• Connections — list existing connections (each exposes an externalId used as a step's auth); get setup guidance.
• Publish / lifecycle — lock and publish a draft (enables it); enable or disable a published flow; delete a flow.
• Test and runs — test a flow end to end; test a single step; list runs; read one run's detail; retry a failed run; run one piece action once without saving a flow.
• iPaaS data tables — list tables, query records, create tables and fields, insert/update/delete records, delete a table.
• AI — list configured AI providers and models for agent-style steps.

Before a destructive catalog operation, show its impact and obtain explicit approval. Prefer updating a step over deleting it.

Steps — build and test a flow

The proven lifecycle: discover, build, validate, test, then publish. A self-contained webhook-to-code flow (no external connection) validated this end to end live.

1. Discover the catalog, then expand the flow-builder entry to read its schema:

   get_ipaas_tools(pipe_id=<pipe_id>)
   get_ipaas_tools(pipe_id=<pipe_id>, tool_name=<flow-builder entry>)

1. Research the pieces you will use and read the exact trigger/action props before building. A trigger often has required config: a webhook trigger, for example, requires an authentication-type property (set it to none for an open URL). Use the piece-research and piece-props entries from the catalog.

1. Build the flow in one call via the flow-builder entry: a trigger plus an ordered list of steps. Reference the trigger output and earlier steps with the host's templating in each step's input. The call returns a flowId and a per-step validity summary.

1. Validate before testing (the validate entry) — reports structural issues without publishing.

1. Test-run end to end via the test entry. It runs in the TESTING environment; allow for long-running tests. Pass mock trigger data when the trigger has no saved sample. A success returns each step's output — treat that payload as the source of truth for the test. Test-run has real side effects for external-app pieces (the action actually fires), so keep test data disposable; self-contained pieces (webhook, schedule, code, tables) are safe.

1. (Optional) Inspect the run with the run-detail entry for full step-by-step output. Read its schema for the exact argument name. Prefer the id returned by the test; if the run is not found, fall back to the run-listing entry or stop, since the test payload already holds the outputs.

1. Publish only on explicit user intent: the lock-and-publish entry locks the draft, publishes it, and enables it (yielding a live webhook URL for webhook triggers). A separate entry enables or disables an already-published flow.

Steps — connect an external app

Any piece that touches an external app (Slack, Gmail, Google Sheets) needs a connection first; pass its externalId as the step's (or trigger's) auth. Self-contained pieces (webhook, schedule, HTTP, code, iPaaS tables) need none.

1. List existing connections (the connection-listing entry) and reuse an externalId if one fits. When several candidates serve the same piece, name them and ask the user rather than pick silently.
2. Token / API-key pieces: one create_ipaas_connection call with the credential (connection_type plus value matching the piece's auth props).
3. OAuth pieces: get_ipaas_connection_auth_url returns a consent URL and a completion bundle; the user authorizes in a browser and pastes back the redirect URL; create_ipaas_connection finishes it. Durable tokens are stored host-side. Creation is an upsert on external_id (reuse an id to rotate a credential).
4. For dropdown fields (Slack channel, sheet, label), resolve options against the connection with the option-resolving entry and use the option value, not the label. Large external workspaces can time out; take the ID from the user and pass it literally, since the action still works at runtime.

Steps — one-shot action (no flow)

For a single task ("send one Slack message", "check my inbox"), the catalog has a run-one-action entry: a piece, action, input, and auth, executed once. No flow is created or saved.

Success criteria

• The validate entry reports the flow ready to publish (all steps valid).
• The test entry returns a success with the expected step outputs.
• The list/structure entries show the flow with a configured trigger and no unconfigured steps.

Failure modes

• Org-level iPaaS disabled. The backend typically returns a permission error (often PERMISSION_DENIED / "iPaaS is disabled for your organization"); nothing in the catalog works. Enable iPaaS on the org or use one that has it.

• Trigger unconfigured after build. A trigger with required props (for example a webhook trigger's authentication type) blocks validation until set. Read its props first, then set them in the trigger input.
• Wrong argument name. Entry schemas are not uniform (a run-detail entry may key the run id differently from how a test entry returns it). Always expand the entry with get_ipaas_tools(pipe_id, tool_name=…) and build arguments from that schema.
• Test-run has real side effects. For external-app pieces the test performs the real action even from a draft. Keep test data disposable; self-contained pieces are safe.
• External step fails with an auth error. The piece needs a connection. Create one and pass its externalId as the step auth; for Slack the bot must be a member of the target channel.
• `PERMISSION_DENIED` on pipe operations under a service account. The service account the flow runs under is not a member of the pipe. Attach it with add_service_account_to_pipe(pipe_id, email, role_name) and confirm with get_pipe_members.
• Dropdown resolution times out. Large external workspaces can time out. Ask the user for the ID and pass it literally.

See also

• pipefy-automations — native if/then rules and AI automations (not iPaaS).
• pipefy-members-email-webhooks — create_webhook for HTTP callbacks on card events; add_service_account_to_pipe to grant a flow's service account pipe membership.
• docs/mcp/tools/ipaas.md and docs/ipaas.md — meta-tool semantics and flow vocabulary.