pipefy-ipaas

iPaaS（高度な自動化）

MCP クライアント： references/mcp.mdをお読みください。CLI ユーザー： references/cli.mdをお読みください。以下の例では、共通の操作引数について説明します。

Pipefy に組み込まれたワークフロー自動化プラットフォームです。フローは、トリガーと、ピース（連携コネクター）を呼び出す一連のステップで構成されます。フロービルダーの動詞は、パイプごとに検出して使用するカタログエントリーであり、固定の操作リストではありません。call_ipaas_toolを通じて呼び出します。

使用する場面

• 「Slack／Gmail／Google Sheets／外部アプリと連携する。」
• ユーザーがPipefyと外部アプリ（Slack、Gmail、Sheetsなど）の連携を求めている場合。デフォルトでは従来型の自動化やAIエージェントではなく、ここにあるiPaaSツールを使用します。
• 「Webhookを受信したときに、Xを実行する。」「スケジュールに従って、Yを実行する。」
• 「ルーター／ループ／コードステップを含む複数ステップのフローを作成する。」
• iPaaSデータテーブルを管理する（Pipefyデータベーステーブルとは別です）。

使用しない場面： カードイベントに対するネイティブなif/thenルールや、プロンプト駆動型のAI自動化。どちらもpipefy-automationsにあります。カードイベントに対するシンプルなHTTPコールバックには、pipefy-members-email-webhooksのcreate_webhookを使用します。

前提条件

• 組織でiPaaSが有効になっていること。 有効でない場合、通常、バックエンドから権限エラーが返されます（多くの場合、PERMISSION_DENIEDというコードと、「iPaaS is disabled for your organization」のようなテキストが含まれます。正確なコードや文字列はバックエンドによって異なります）。

• パイプでオートメーションを作成する権限があること（パイプ管理者の権限）。

• サービスアカウントがパイプのメンバーであること。 フローがサービスアカウントとして実行される場合、そのアカウントは対象のパイプのメンバーである必要があります。そうでないと、フローの構築後であっても、そのアカウントのIDで実行されるパイプスコープの呼び出しは権限エラーになります。組織レベルでアカウントを追加するだけでは不十分です。必要に応じてcreate_service_accountでアカウントを作成し、すぐにadd_service_account_to_pipe(pipe_id, email, role_name)で追加してください。pipefy-members-email-webhooksおよびdocs/mcp/tools/service-accounts.mdを参照してください。カタログ操作では呼び出し元セッションのIDが使用されるため、この要件はカタログの呼び出し元ではなく、フローの実行に使うサービスアカウントに適用されます。

• iPaaSワークスペースはパイプごとです。カタログと既存のフロー、接続、テーブルはそれぞれ1つのpipe_idに属するため、2つのパイプに対して同じ呼び出しをしても結果が異なる場合があります。

操作

操作	読み取り専用	目的
get_ipaas_tools	はい	パイプごとのカタログを簡潔に取得します。またはtool_nameを指定して、1つのエントリーの完全な入力スキーマを展開します。
call_ipaas_tool	いいえ	スキーマに一致するargumentsを指定し、名前でカタログエントリーを1つ呼び出します。
get_ipaas_connection_auth_url	いいえ	OAuth接続を開始します。ユーザーに渡す同意URLと、完了用の情報一式を返します。
create_ipaas_connection	いいえ	OAuth接続を完了するか、トークンまたはAPIキーによる接続を直接作成します。

操作カタログを確認する

カタログは大規模で（フローの構築、テスト、テーブル、実行など）、入力スキーマが非常に大きい項目もあります。すべてを読み込まないでください。次の3つの手順で進めます。

1. get_ipaas_tools(pipe_id) — 各項目の name と1行の説明を含む簡潔なカタログを取得します。
2. get_ipaas_tools(pipe_id, tool_name="...") — 使用する直前に、1つの項目の詳細な説明と inputSchema を取得します。
3. call_ipaas_tool(pipe_id, tool_name="...", arguments={...}) — 項目を呼び出します。引数はそのまま転送され、iPaaS ホストが検証し、エラーメッセージが返されます。

呼び出す直前の項目以外は展開しないでください。引数名はカタログ全体で統一されていないため、正確な引数名は各項目のスキーマを確認してください。機能別に見ると、カタログでは次の操作を利用できます。

• フローを作成する — トリガーとステップを含むフローを1回の呼び出しで作成する、個々のステップを追加または更新する、トリガーを設定または更新する、条件付きルーターの分岐を追加する、フローの名前を変更または複製する。ステップには、インテグレーションピース、コードステップ、ループ、ルーターを指定できます（コードよりピースを優先してください）。
• フローを調査する — フローの一覧を取得する、フローのステップツリーと各ステップの有効性を確認する、公開前にフローを検証する。
• ピースを探す — ピースカタログを検索する（完全一致またはあいまい検索）、ピースのアクションまたはトリガーの入力プロパティを確認する、ドロップダウンの選択肢を解決する、適用前にステップ設定を検証する。
• 接続 — 既存の接続を一覧表示する（各接続には、ステップの auth として使われる externalId が含まれます）、設定方法のガイダンスを取得する。
• 公開／ライフサイクル — 下書きをロックして公開する（有効化されます）、公開済みのフローを有効または無効にする、フローを削除する。
• テストと実行 — フローを最初から最後までテストする、単一ステップをテストする、実行の一覧を取得する、実行の詳細を確認する、失敗した実行を再試行する、フローを保存せずにピースのアクションを1回実行する。
• iPaaS データテーブル — テーブルの一覧を取得する、レコードをクエリする、テーブルとフィールドを作成する、レコードを挿入／更新／削除する、テーブルを削除する。
• AI — エージェント形式のステップ用に設定された AI プロバイダーとモデルの一覧を取得する。

破壊的なカタログ操作を行う前に、影響を示して明示的な承認を得てください。ステップを削除するより、更新することを優先してください。

手順 — フローを構築してテストする

実証済みのライフサイクルは、検出、構築、検証、テスト、公開です。外部接続を使わない、自己完結型の Webhook からコードへのフローで、この一連の流れを実際に最初から最後まで検証しました。

1. 検出：カタログを確認し、フロービルダーの項目を展開してスキーマを読みます。

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

2. 各要素を調査：使用する要素を調べ、構築前にトリガー／アクションの正確なプロパティを確認します。トリガーには必須設定があることがよくあります。たとえば Webhook トリガーでは、認証タイプのプロパティが必須です（公開 URL にするには none に設定します）。カタログのピース調査項目とピースプロパティ項目を使用してください。

3. フローを構築：フロービルダーの項目を使い、トリガーと順序付きのステップ一覧を1回の呼び出しで指定します。各ステップの入力では、ホストのテンプレート構文を使ってトリガーの出力や前のステップを参照します。呼び出しは flowId と、ステップごとの有効性の概要を返します。

4. 検証：テスト前に検証項目を実行します。公開せずに構造上の問題を報告します。

5. テスト実行：テスト項目を使って、最初から最後まで実行します。TESTING 環境で実行されるため、時間のかかるテストを考慮してください。トリガーに保存済みのサンプルがない場合は、モックのトリガーデータを渡します。成功すると各ステップの出力が返されます。このペイロードをテストの信頼できる情報源として扱ってください。外部アプリのピースでは、テスト実行に実際の副作用があります（アクションが実際に実行されます）。そのため、テストデータは使い捨てにしてください。自己完結型のピース（Webhook、スケジュール、コード、テーブル）は安全です。

6. （任意）実行を確認：実行詳細項目を使うと、ステップごとの出力をすべて確認できます。正確な引数名については、そのスキーマを読んでください。テストで返された ID を優先します。実行が見つからない場合は、実行一覧項目に切り替えるか、そこで終了してください。テストのペイロードにすでに出力が含まれているためです。

7. 公開：ユーザーが明示的に求めた場合にのみ公開します。ロックして公開する項目は、ドラフトをロックして公開し、有効化します（Webhook トリガーの場合は、稼働中の Webhook URL が得られます）。公開済みのフローを有効化または無効化する別の項目もあります。

手順 — 外部アプリに接続する

外部アプリ（Slack、Gmail、Google Sheets）に関係するピースには、まず接続が必要です。externalId をステップ（またはトリガー）の auth として渡します。自己完結型のピース（Webhook、スケジュール、HTTP、コード、iPaaS テーブル）には接続は不要です。

1. 既存の接続を一覧表示する接続一覧項目を使い、適合する externalId があれば再利用します。同じピースに使える候補が複数ある場合は、それらの名前を示してユーザーに尋ねてください。黙って選ばないでください。
2. トークン／API キーを使うピース：認証情報（connection_type と、ピースの認証プロパティに対応する value）を指定して、create_ipaas_connection を1回呼び出します。
3. OAuth を使うピース：get_ipaas_connection_auth_url は、同意 URL と完了用の情報一式を返します。ユーザーはブラウザーで認証し、リダイレクト URL を貼り付けます。その後、create_ipaas_connection で処理を完了します。永続トークンはホスト側に保存されます。作成時は external_id に対するアップサートが行われます（認証情報を更新する場合は同じ ID を再利用します）。
4. ドロップダウンのフィールド（Slack チャンネル、シート、ラベル）では、選択肢取得項目を使って接続に対する選択肢を解決し、ラベルではなく選択肢の value を使います。外部の大規模なワークスペースではタイムアウトすることがあります。その場合はユーザーから ID を取得して、そのまま渡してください。アクションは実行時に機能します。

手順 — 単発のアクション（フローなし）

単一のタスク（「Slack メッセージを1件送信する」「受信トレイを確認する」など）では、カタログのアクション単発実行項目を使います。ピース、アクション、input、auth を指定して1回実行します。フローは作成も保存もされません。

成功条件

• 検証項目が、フローを公開できる状態（すべてのステップが有効）だと報告すること。
• テスト項目が、想定したステップ出力とともに成功を返すこと。
• 一覧／構造項目に、トリガーが設定され、未設定のステップがないフローが表示されること。

失敗するケース

• 組織レベルで iPaaS が無効になっています。 通常、バックエンドは権限エラー（多くの場合、PERMISSION_DENIED / 「iPaaS is disabled for your organization」）を返し、カタログ内の何も機能しません。組織で iPaaS を有効にするか、有効になっている組織を使用してください。

• ビルド後にトリガーが未設定です。 必須のプロパティ（たとえば、webhook トリガーの認証タイプ）があるトリガーは、設定するまで検証を妨げます。まずそのプロパティを読み取り、次にトリガーの入力で設定してください。

• 引数名が間違っています。 エントリーのスキーマは統一されていません（実行詳細のエントリーでは、テストエントリーが返すものとは異なる名前で実行 ID が指定されている場合があります）。必ず get_ipaas_tools(pipe_id, tool_name=…) でエントリーを展開し、そのスキーマに基づいて引数を組み立ててください。

• テスト実行でも実際の副作用が発生します。 外部アプリのピースでは、下書きからでもテストによって実際のアクションが実行されます。テストデータは破棄可能なものにしてください。自己完結型のピースは安全です。

• 外部ステップで認証エラーが発生します。 ピースには接続が必要です。接続を作成し、その externalId をステップの auth として渡してください。Slack の場合、ボットが対象チャンネルのメンバーである必要があります。

• サービスアカウントでパイプを操作すると PERMISSION_DENIED が発生します。 フローの実行に使用するサービスアカウントが、パイプのメンバーではありません。add_service_account_to_pipe(pipe_id, email, role_name) で追加し、get_pipe_members で確認してください。

• ドロップダウンの解決がタイムアウトします。 大規模な外部ワークスペースではタイムアウトすることがあります。ユーザーに ID を尋ね、そのまま渡してください。

関連項目

• pipefy-automations — ネイティブの if/then ルールと AI オートメーション（iPaaS ではありません）。
• pipefy-members-email-webhooks — カードイベントの HTTP コールバックには create_webhook を、フローのサービスアカウントにパイプのメンバー資格を付与するには add_service_account_to_pipe を使用します。
• docs/mcp/tools/ipaas.md と docs/ipaas.md — メタツールのセマンティクスとフローの用語。