Activepieces Flow Builder

[Discovery] List flows in the current project with status, trigger type, and published state.

[Discovery] Get the full structure of a flow: step tree, configuration status, step input values, router branch conditions, and valid insert locations. Shows the actual configured inputs for each step (URL, body, headers, etc.) so the AI can read and edit existing configurations.

[Discovery] Read the full source code, package.json, and input mappings of a CODE step. Returns untruncated content — unlike ap_flow_structure which truncates code to 300 characters. Use this tool when you need to read or edit a CODE step's full source. ap_flow_structure truncates code for overview purposes, so always call ap_read_step_code before modifying a code step.

[Discovery] Read the full untruncated settings of any step, including the trigger: piece input, action/trigger name, loop items, router branches, and error handling options. Use this to see a step's current configuration before updating it — ap_flow_structure truncates piece input.

[Discovery] Validate a flow for structural issues without publishing. Checks step validity, template references, and empty branches.

[Discovery] Research available pieces. Use pieceNames for bulk exact lookup (always returns actions and triggers). Use searchQuery for fuzzy discovery.

[Discovery] Find piece actions by describing the task in natural language (e.g. *"send a message to a Slack channel"*). Returns the most relevant actions ranked by semantic similarity, or an empty list when nothing in the catalog matches — the tool does not force a match. Each result includes the piece name, action name, a one-line description, whether the action needs a connection, and a connected flag indicating whether the project already has a connection for that piece.

[Discovery] Find piece triggers (the event that starts a flow) by describing when the flow should run (e.g. *"when a new row is added to a Google Sheet"*). Same behavior and result shape as ap_search_actions, returning trigger names instead of action names.

[Discovery] Get the detailed input property schema for a specific piece action or trigger. Returns field names, types, required/optional, descriptions, default values, and dropdown options. When auth is required but not provided, automatically lists available connections. Use this before ap_update_step or ap_update_trigger to know exactly which fields to set.

[Discovery] Resolve dropdown options for a single piece property. Returns available choices with labels and internal IDs. Use this to discover valid values for dynamic dropdown fields (e.g., Slack channels, Google Sheets, email labels) before configuring a step. Each option in the response has a label (human-readable name) and a value (internal ID). Always pass the value when configuring a step — never use the label. For example, if the response includes {label: "general", value: "C1234567890"}, use "C1234567890" as the channel value.

[Discovery] Resolve a chain of dependent dropdown properties in one call. For actions with cascading fields (e.g., Spreadsheet → Sheet → Columns), this resolves each property sequentially, feeding each selected value into the next resolution. Pass selectedValue for properties whose value you already know; the tool stops and returns options when it hits a property without a selectedValue. Use this instead of multiple ap_resolve_property_options calls when fields depend on each other. For example, to resolve Google Sheets columns: pass spreadsheetId and sheetId with their selectedValue, and values without — the tool resolves the full chain and returns the column fields in one call.

[Discovery] Validate a step configuration before applying it. Returns field-level errors without modifying any flow.

[Discovery] List OAuth/app connections in the project. Required before adding steps that need authentication.

[Discovery] List configured AI providers and their available models. Use this to discover valid aiProviderModel values for configuring Run Agent steps.

[Discovery] List all tables in the project with their fields (name, type, id) and row counts.

[Discovery] Query records from a table with optional filtering.

[Discovery] List recent flow runs with optional filters.

[Discovery] Get detailed results of a flow run including step-by-step outputs, errors, and durations.

[Discovery] Get step-by-step instructions for setting up connections or AI providers. Returns instructions for the user to follow in the UI — credentials are never handled through MCP.

[Discovery] Set or clear the active project context. All tools require a project context to operate. Call with a projectId to select a project, or without to clear the selection. Always returns the list of available projects.

[Flow Management] Create a new empty flow.

[Flow Management] Duplicate an existing flow. Creates a new copy with all steps, configuration, and canvas notes. Connections and sample data are not copied. After duplicating, use ap_flow_structure on the new flow to check configuration status. Steps that reference connections will need to be re-configured with ap_update_step.

[Flow Management] Rename an existing flow.

[Flow Management] Enable or disable a flow.

[Flow Management] Permanently delete a flow and all its versions. This cannot be undone.

[Flow Management] Publish the current draft of a flow. Validates all steps are configured.

[Flow Building] Create a complete flow in one call — trigger plus any number of steps. Steps are added sequentially (trigger → step_1 → step_2 → ...). All steps are validated on creation. Use granular tools (ap_add_step, ap_update_step) to modify existing flows or add nested structures (loop contents, router branches). Returns the flow ID, a direct flowUrl link to the flow in the editor, step count, and validation status.

[Flow Building] Set or update the trigger for a flow.

[Flow Building] Add a new step to a flow. Optionally configure it in the same call by providing input, auth, sourceCode, or loopItems.

[Flow Building] Update an existing step's settings. Auto-fills default values for optional properties. Use {{stepName.field}} syntax in input values to reference data from previous steps (e.g., {{trigger.body.email}}, {{step_1.id}}). Do NOT include .output. in the path.

[Flow Building] Delete a step from a flow.

[Router & Branching] Add a conditional branch to a router step. The branch is inserted before the fallback (Otherwise) branch.

[Router & Branching] Update the conditions and/or name of an existing router branch without affecting the steps inside it. Cannot set conditions on the fallback branch — only branchName can be updated for fallback branches.

[Router & Branching] Delete a branch from a router step. Cannot delete the fallback (last) branch.

[Annotations] Add, update, or delete canvas notes on a flow.

[Tables] Create a new table with an initial set of fields.

[Tables] Permanently delete a table and all its data.

[Tables] Add, rename, or delete fields on a table.

[Tables] Insert one or more records into a table.

[Tables] Update specific cells in a record. Only specified fields are changed.

[Tables] Permanently delete one or more records.

[Testing & Runs] Test a flow end-to-end in the test environment. Pass triggerTestData to provide mock trigger output when no sample data exists (e.g., for webhook triggers). The flow must have a configured trigger. The tool validates this before running and returns a clear error if not.

[Testing & Runs] Test a single step within a flow. Runs all steps up to and including the target step. Pass triggerTestData when no sample data exists.

[Testing & Runs] Retry a failed flow run.

[Testing & Runs] Execute a single piece action once without building or saving a flow. Designed for one-shot tasks like *"check my inbox"* or *"send one Slack message"* where building a full automation would be overkill. Under the hood the action runs directly in the engine and the result is returned immediately — no flow is created, and nothing appears in the user's flow list. When to pick this vs. ap_build_flow:

• ap_run_action — one-off, throwaway, returns a result now.
• ap_build_flow — persistent automation that should repeat, run on a schedule, or trigger on external events.

Prefer calling ap_list_connections and ap_get_piece_props first so you know the exact actionName, the expected props, and the right connectionExternalId before invoking. Missing required inputs or unknown actions produce a friendly error before dispatch — no run is created and nothing is billed.