pipefy-ipaas

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iPaaS (Advanced Automations)

iPaaS（高级自动化）

Pipefy's embedded workflow-automation platform. A flow is a trigger plus a sequence of steps that call pieces (integration connectors). The MCP server exposes it through 4 meta-tools: the flow-builder verbs are catalog entries you discover per pipe and invoke through

call_ipaas_tool

, never a fixed tool list.

Pipefy的嵌入式工作流自动化平台。flow（流程）是由一个触发器加上一系列调用pieces（集成连接器）的步骤组成。MCP服务器通过4个元工具对外提供该功能：流程构建器的操作是每个管道对应的目录条目，需通过

call_ipaas_tool

调用，而非固定工具列表。

When to use

使用场景

"Integrate with Slack / Gmail / Google Sheets / an external app."
"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 skills/automations/pipefy-automations/SKILL.md. Simple HTTP callbacks on card events are

create_webhook

in skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md.

"与Slack / Gmail / Google Sheets / 外部应用集成。"
"当webhook传入时，执行操作X。" "按调度执行操作Y。"
"构建包含路由/循环/代码步骤的多步骤流程。"
管理iPaaS数据表（与Pipefy数据库表相互独立）。

**非适用场景：**卡片事件的原生if/then规则，或提示驱动的AI自动化，这两类功能均在skills/automations/pipefy-automations/SKILL.md中。卡片事件的简单HTTP回调功能是skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md中的

create_webhook

。

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).
iPaaS OAuth client configured on this MCP server. If
```
PIPEFY_IPAAS_OAUTH_CLIENT_ID
```
is blank, every tool returns a "disabled on this server" message (server-config disable, distinct from the org-level one).
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 skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md and docs/mcp/tools/service-accounts.md. The 4 meta-tools themselves act as the calling session's identity, so this applies to the service account your flow runs under, not to these tools.
MCP-only. The 4 meta-tools have no CLI twin (deferred in docs/parity.md);
```
add_service_account_to_pipe
```
is available on both MCP and CLI.
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.
Under
```
profile=remote
```
,
```
$env
```
secret references in arguments are rejected.

组织已启用iPaaS。若未启用，后端通常会返回权限错误（常编码为
```
PERMISSION_DENIED
```
，提示文本类似“iPaaS在您的组织中已禁用”——具体编码/字符串由后端决定）。
MCP服务器已配置iPaaS OAuth客户端。若
```
PIPEFY_IPAAS_OAUTH_CLIENT_ID
```
为空，所有工具都会返回“此服务器上已禁用”的提示（服务器配置层面禁用，与组织层面禁用不同）。
拥有在管道上创建自动化的权限（管道管理员权限）。
服务账号必须是管道成员。当流程在服务账号下运行时，该账号必须是目标管道的成员，否则即使流程已构建，以其身份发起的管道范围调用也会因权限错误失败。仅在组织层面添加账号是不够的。若需要，可使用
```
create_service_account
```
创建服务账号，然后立即通过
```
add_service_account_to_pipe(pipe_id, email, role_name)
```
将其添加到管道中——详情见skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md和docs/mcp/tools/service-accounts.md。4个元工具本身使用调用会话的身份，因此此要求适用于流程运行所依赖的服务账号，而非这些元工具。
仅适用于MCP。这4个元工具没有对应的CLI版本（相关计划推迟至docs/parity.md中）；
```
add_service_account_to_pipe
```
在MCP和CLI中均可用。
iPaaS工作空间按管道划分：目录及所有现有流程、连接和数据表都属于某个
```
pipe_id
```
，因此针对两个管道的相同调用可能会有不同结果。
在
```
profile=remote
```
模式下，参数中的
```
$env
```
密钥引用会被拒绝。

Tools needed (MCP)

所需工具（MCP）

Tool (MCP)	Read-only	Purpose
`get_ipaas_tools`	Yes	Discover the per-pipe catalog (compact), or with `tool_name` expand one entry's full input schema.
`call_ipaas_tool`	No	Invoke one catalog entry by name with `arguments` matching its schema.
`get_ipaas_connection_auth_url`	No	Start an OAuth connection: returns a consent URL to hand the user, plus a completion bundle.
`create_ipaas_connection`	No	Finish an OAuth connection, or create a token / API-key one directly.

工具（MCP）	是否只读	用途
`get_ipaas_tools`	是	发现每个管道对应的目录（精简版），或传入 `tool_name` 获取某个条目的完整输入 schema。
`call_ipaas_tool`	否	根据名称调用某个目录条目，传入符合其schema的 `arguments` 参数。
`get_ipaas_connection_auth_url`	否	启动OAuth连接：返回供用户使用的授权URL，以及完成包。
`create_ipaas_connection`	否	完成OAuth连接，或直接创建令牌/API密钥类型的连接。

The meta-tool pattern

元工具模式

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:

```
get_ipaas_tools(pipe_id)
```
— compact catalog: each entry's
```
name
```
and one-line description.
```
get_ipaas_tools(pipe_id, tool_name="...")
```
— one entry's full description and
```
inputSchema
```
, fetched right before you use it.
```
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.

Destructive entries (delete flow, delete table, delete records, delete step) are permanent and have no preview. Reserve them for explicit user intent.

目录规模庞大（涵盖流程构建、测试、数据表、运行等），部分条目包含非常大的输入schema。请勿全部加载。请按以下三步操作：

```
get_ipaas_tools(pipe_id)
```
—— 获取精简版目录：每个条目的
```
name
```
和一行描述。
```
get_ipaas_tools(pipe_id, tool_name="...")
```
—— 获取某个条目的完整描述和
```
inputSchema
```
，请在即将使用前获取。
```
call_ipaas_tool(pipe_id, tool_name="...", arguments={...})
```
—— 调用该条目。参数会直接转发；iPaaS主机将验证参数，并返回错误信息。

请勿展开超过即将调用的条目，并阅读条目的schema以获取准确的参数名称（目录中的参数名称并不统一）。目录按功能分组提供以下内容：

创建流程 —— 一次调用创建流程（触发器加步骤）；添加或更新单个步骤；设置或更新触发器；添加条件路由分支；重命名或复制流程。步骤可以是集成连接器、代码步骤、循环或路由（优先使用连接器而非代码）。
查看流程 —— 列出流程；读取流程的步骤树和每个步骤的有效性；发布前验证流程。
发现连接器 —— 搜索连接器目录（精确或模糊搜索）；读取连接器动作/触发器的输入属性；解析下拉选项值；应用前验证步骤配置。
连接管理 —— 列出现有连接（每个连接都会暴露一个
```
externalId
```
，用作步骤的
```
auth
```
参数）；获取设置指南。
发布/生命周期管理 —— 锁定并发布草稿（启用流程）；启用或禁用已发布的流程；删除流程。
测试与运行 —— 端到端测试流程；测试单个步骤；列出运行记录；读取单个运行记录的详细信息；重试失败的运行；无需保存流程即可单次运行某个连接器动作。
iPaaS数据表 —— 列出数据表、查询记录、创建数据表和字段、插入/更新/删除记录、删除数据表。
AI相关 —— 列出为Agent风格步骤配置的AI提供商和模型。

破坏性条目（删除流程、删除数据表、删除记录、删除步骤）是永久性的，且无预览功能。仅在用户明确要求时使用。

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.

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>

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.
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.
Validate before testing (the validate entry) — reports structural issues without publishing.
Test-run end to end via the test entry. It runs in the TESTING environment; every
```
call_ipaas_tool
```
has a ~120s network budget (most relevant here for long runs). 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.
(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.
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.

经过验证的生命周期：发现、构建、验证、测试、发布。一个独立的webhook到代码的流程（无需外部连接）已通过端到端的实时验证。

发现目录，然后展开流程构建器条目以读取其schema：

get_ipaas_tools pipe_id=<pipe_id>
get_ipaas_tools pipe_id=<pipe_id> tool_name=<flow-builder entry>

研究将要使用的连接器，并在构建前读取准确的触发器/动作属性。触发器通常需要配置必填项：例如webhook触发器需要身份验证类型属性（若为开放URL，可设置为无）。使用目录中的连接器研究和连接器属性条目。
通过流程构建器条目构建流程：一次调用完成触发器加有序步骤列表的创建。在每个步骤的输入中使用主机的模板语法引用触发器输出和之前的步骤。调用会返回
```
flowId
```
和每个步骤的有效性摘要。
测试前验证（使用验证条目）——在不发布的情况下报告结构问题。
通过测试条目进行端到端测试运行。测试在TESTING环境中运行；每个
```
call_ipaas_tool
```
有约120秒的网络预算（长时间运行时此限制最为相关）。若触发器没有保存的样本数据，请传入模拟触发器数据。成功后会返回每个步骤的输出——请将该负载作为测试的事实来源。测试运行对外部应用连接器会产生实际影响（动作会真实执行），因此请使用可丢弃的测试数据；独立连接器（webhook、调度、代码、数据表）是安全的。
（可选）使用运行详情条目查看运行记录，获取完整的分步输出。读取其schema以获取准确的参数名称。优先使用测试返回的id；若未找到运行记录，可退而使用运行列表条目或停止操作，因为测试负载已包含输出内容。
仅在用户明确要求时发布：锁定并发布条目会锁定草稿、发布流程并启用它（对于webhook触发器，会生成一个实时webhook URL）。另有单独的条目用于启用或禁用已发布的流程。

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.

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.
Token / API-key pieces: one
```
create_ipaas_connection
```
call with the credential (
```
connection_type
```
plus
```
value
```
matching the piece's auth props). To keep the secret out of the conversation, set it in the server environment and reference it as
```
{"$env": "PIPEFY_IPAAS_CONNECTION_<NAME>"}
```
(local servers only; rejected under
```
profile=remote
```
).
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).
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.

任何涉及外部应用（Slack、Gmail、Google Sheets）的连接器都需要先建立连接；将其

externalId

作为步骤（或触发器）的

auth

参数传入。独立连接器（webhook、调度、HTTP、代码、iPaaS数据表）无需连接。

列出现有连接（使用连接列表条目），若有合适的连接，复用其
```
externalId
```
。若有多个候选连接适合同一个连接器，请列出名称并询问用户，而非静默选择。
令牌/API密钥类型连接器：调用一次
```
create_ipaas_connection
```
，传入凭据（
```
connection_type
```
加上符合连接器认证属性的
```
value
```
）。为避免在对话中暴露密钥，请将其设置在服务器环境中，并以
```
{"$env": "PIPEFY_IPAAS_CONNECTION_<NAME>"}
```
的形式引用（仅适用于本地服务器；
```
profile=remote
```
模式下会被拒绝）。
OAuth类型连接器：
```
get_ipaas_connection_auth_url
```
会返回授权URL和完成包；用户在浏览器中完成授权后粘贴回重定向URL；
```
create_ipaas_connection
```
完成连接创建。持久令牌会存储在主机端。创建操作会根据
```
external_id
```
执行更新插入（复用id可轮换凭据）。
对于下拉字段（Slack频道、表格、标签），使用选项解析条目根据连接解析选项，并使用选项的
```
value
```
而非标签。大型外部工作空间可能会超时；请向用户索要ID并直接传入，因为运行时动作仍可正常工作。

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.

对于单个任务（“发送一条Slack消息”、“检查我的收件箱”），目录中有一个运行单次动作的条目：指定连接器、动作、

input

和

auth

，即可执行一次。不会创建或保存流程。

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.
Server-config iPaaS disabled. When
```
PIPEFY_IPAAS_OAUTH_CLIENT_ID
```
is blank, tools return "disabled on this server" — restore the default or set a client id.
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.
$env
rejected under remote profile. Secret references are local-only. Pass credentials through
```
create_ipaas_connection
```
, not inline
```
$env
```
.
Accidental destruction. Delete entries (flow, table, records) are permanent and have no preview. Confirm intent first; prefer updating a step over deleting it (delete destroys sample data).

组织层面iPaaS已禁用。后端通常会返回权限错误（常为
```
PERMISSION_DENIED
```
/ “iPaaS在您的组织中已禁用”）；目录中的所有功能均无法使用。请在组织中启用iPaaS或使用已启用iPaaS的组织。
服务器配置层面iPaaS已禁用。当
```
PIPEFY_IPAAS_OAUTH_CLIENT_ID
```
为空时，工具会返回“此服务器上已禁用”——请恢复默认设置或设置客户端id。
构建后触发器未配置。带有必填属性的触发器（例如webhook触发器的身份验证类型）会阻止验证，直到完成配置。请先读取其属性，然后在触发器输入中设置。
参数名称错误。条目schema并不统一（运行详情条目对运行id的键名可能与测试条目返回的键名不同）。请始终使用
```
get_ipaas_tools(pipe_id, tool_name=…)
```
展开条目，并根据该schema构建参数。
测试运行产生实际影响。对于外部应用连接器，即使是草稿流程的测试也会执行真实动作。请使用可丢弃的测试数据；独立连接器是安全的。
外部步骤因认证错误失败。连接器需要连接。请创建连接并将其
```
externalId
```
作为步骤的
```
auth
```
参数传入；对于Slack，机器人必须是目标频道的成员。
服务账号下的管道操作出现
PERMISSION_DENIED
错误。流程运行所依赖的服务账号不是管道成员。请使用
```
add_service_account_to_pipe(pipe_id, email, role_name)
```
将其添加到管道中，并通过
```
get_pipe_members
```
确认。
下拉选项解析超时。大型外部工作空间可能会超时。请向用户索要ID并直接传入。
远程模式下
$env
被拒绝。密钥引用仅适用于本地。请通过
```
create_ipaas_connection
```
传入凭据，而非内联
```
$env
```
。
意外销毁。删除条目（流程、数据表、记录）是永久性的，且无预览功能。请先确认用户意图；优先更新步骤而非删除（删除会销毁样本数据）。

另请参阅

skills/automations/pipefy-automations/SKILL.md — native if/then rules and AI automations (not iPaaS).
skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md —
```
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.

skills/automations/pipefy-automations/SKILL.md —— 原生if/then规则和AI自动化（非iPaaS）。
skills/members-email-webhooks/pipefy-members-email-webhooks/SKILL.md —— 卡片事件HTTP回调的
```
create_webhook
```
；为流程的服务账号授予管道成员身份的
```
add_service_account_to_pipe
```
。
docs/mcp/tools/ipaas.md和docs/ipaas.md —— 元工具语义和流程术语。