> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools Reference
> Complete catalog of all MCP tools available in Activepieces
## Discovery
These tools are always available (locked) and read-only. They help AI agents understand what's in the project before making changes.
### ap\_list\_flows
List flows in the current project with status, trigger type, and published state.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------ |
| `limit` | number | No | Max flows to return (default 100, max 500) |
| `status` | string | No | Filter by status: `ENABLED` or `DISABLED` |
| `name` | string | No | Filter by flow name (partial match) |
### ap\_flow\_structure
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.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ----------- |
| `flowId` | string | Yes | The flow ID |
### ap\_read\_step\_code
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.
| Input | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------ |
| `flowId` | string | Yes | The flow ID |
| `stepName` | string | Yes | The name of the CODE step (e.g., `step_1`) |
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.
### ap\_validate\_flow
Validate a flow for structural issues without publishing. Checks step validity, template references, and empty branches.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ----------- |
| `flowId` | string | Yes | The flow ID |
### ap\_research\_pieces
Research available pieces. Use `pieceNames` for bulk exact lookup (always returns actions and triggers). Use `searchQuery` for fuzzy discovery.
| Input | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------ |
| `pieceNames` | string\[] | No | Exact piece names to look up (always returns actions and triggers) |
| `searchQuery` | string | No | Filter pieces by name |
| `includeActions` | boolean | No | Include action details (only applies to searchQuery mode) |
| `includeTriggers` | boolean | No | Include trigger details (only applies to searchQuery mode) |
### ap\_get\_piece\_props
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.
| Input | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `pieceName` | string | Yes | Piece name (e.g., `@activepieces/piece-slack`) |
| `actionOrTriggerName` | string | Yes | Action or trigger name (e.g., `send_channel_message`) |
| `type` | string | Yes | `action` or `trigger` |
| `auth` | string | No | Connection externalId. When provided, dynamic dropdowns and DYNAMIC sub-fields are resolved. |
| `flowId` | string | No | Flow ID for resolving dependent dropdowns that need step context. |
| `input` | object | No | Known input values for resolving dependent DYNAMIC properties (e.g., `{"body_type": "json"}`). |
### ap\_resolve\_property\_options
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.
| Input | Type | Required | Description |
| --------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `pieceName` | string | Yes | Piece name (e.g., `@activepieces/piece-slack`) |
| `actionOrTriggerName` | string | Yes | Action or trigger name (e.g., `send_channel_message`) |
| `type` | string | Yes | `action` or `trigger` |
| `propertyName` | string | Yes | The exact property name to resolve (e.g., `channel`) |
| `auth` | string | Yes | Connection externalId — required to fetch options from the user's account |
| `input` | object | No | Values for parent properties that this field depends on (refreshers) |
| `searchValue` | string | No | Search term to filter results for large dropdown lists (e.g., "sales" to find sales-related channels) |
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.
### ap\_validate\_step\_config
Validate a step configuration before applying it. Returns field-level errors without modifying any flow.
| Input | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------- |
| `stepType` | string | Yes | `PIECE_ACTION`, `PIECE_TRIGGER`, `CODE`, `LOOP_ON_ITEMS`, or `ROUTER` |
| `pieceName` | string | No | For PIECE types: piece name (short names like `slack` accepted) |
| `actionName` | string | No | For PIECE\_ACTION: action name |
| `triggerName` | string | No | For PIECE\_TRIGGER: trigger name |
| `input` | object | No | For PIECE types: input config to validate |
| `auth` | string | No | For PIECE types: any non-empty string indicates auth is provided |
| `sourceCode` | string | No | For CODE: JavaScript/TypeScript source code |
| `packageJson` | string | No | For CODE: package.json as JSON string |
| `loopItems` | string | No | For LOOP\_ON\_ITEMS: items expression |
| `settings` | object | No | For ROUTER: raw router settings |
### ap\_list\_connections
List OAuth/app connections in the project. Required before adding steps that need authentication.
| Input | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `pieceName` | string | No | Filter by piece name. Short names like `slack` or `google-sheets` are auto-expanded. |
| `displayName` | string | No | Filter by connection display name (partial match) |
| `status` | array | No | Filter by status: `ACTIVE`, `MISSING`, or `ERROR` |
### ap\_list\_ai\_models
List configured AI providers and their available models. Use this to discover valid `aiProviderModel` values for configuring Run Agent steps.
| Input | Type | Required | Description |
| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `provider` | string | No | Filter by provider (`openai`, `anthropic`, `google`, `azure`, `openrouter`, `activepieces`, `cloudflare-gateway`, `custom`) |
### ap\_list\_tables
List all tables in the project with their fields (name, type, id) and row counts.
| Input | Type | Required | Description |
| ----- | ---- | -------- | ------------------ |
| — | — | — | No inputs required |
### ap\_find\_records
Query records from a table with optional filtering.
| Input | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------- |
| `tableId` | string | Yes | The table ID |
| `filters` | array | No | Filter conditions (fieldName, operator, value) |
| `limit` | number | No | Max records (default 50, max 500) |
**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `co` (contains), `exists`, `not_exists`
### ap\_list\_runs
List recent flow runs with optional filters.
| Input | Type | Required | Description |
| -------- | ------ | -------- | --------------------------------------------------- |
| `flowId` | string | No | Filter by flow |
| `status` | string | No | Filter by status (SUCCEEDED, FAILED, RUNNING, etc.) |
| `limit` | number | No | Max runs (default 10, max 50) |
### ap\_get\_run
Get detailed results of a flow run including step-by-step outputs, errors, and durations.
| Input | Type | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `flowRunId` | string | Yes | The run ID |
### ap\_setup\_guide
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.
| Input | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------- |
| `topic` | string | Yes | `connection` or `ai_provider` |
| `pieceName` | string | No | For connections: which piece needs auth |
***
## Flow Management
Create and manage flows.
### ap\_create\_flow
Create a new empty flow.
| Input | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------- |
| `flowName` | string | Yes | Display name for the flow |
### ap\_duplicate\_flow
Duplicate an existing flow. Creates a new copy with all steps, configuration, and canvas notes. Connections and sample data are not copied.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------------- |
| `flowId` | string | Yes | The flow ID to duplicate |
| `name` | string | No | Name for the copy (defaults to "Copy of \{original name}") |
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`.
### ap\_rename\_flow
Rename an existing flow.
| Input | Type | Required | Description |
| ------------- | ------ | -------- | ----------- |
| `flowId` | string | Yes | The flow ID |
| `displayName` | string | Yes | New name |
### ap\_change\_flow\_status
Enable or disable a flow.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ----------------------- |
| `flowId` | string | Yes | The flow ID |
| `status` | string | Yes | `ENABLED` or `DISABLED` |
### ap\_delete\_flow
Permanently delete a flow and all its versions. This cannot be undone.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------- |
| `flowId` | string | Yes | The ID of the flow to delete |
### ap\_lock\_and\_publish
Publish the current draft of a flow. Validates all steps are configured.
| Input | Type | Required | Description |
| -------- | ------ | -------- | ----------- |
| `flowId` | string | Yes | The flow ID |
***
## Flow Building
Add, configure, and remove steps in a flow.
### ap\_build\_flow
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).
| Input | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `flowName` | string | Yes | Name for the new flow |
| `trigger` | object | Yes | `{pieceName, triggerName, input?, auth?}` |
| `steps` | array | Yes | Array of step specs, each with `type`, `displayName`, and type-specific fields |
**Step types in the array:**
* **PIECE**: `pieceName`, `actionName`, `input`, `auth`, `continueOnFailure`, `retryOnFailure`
* **CODE**: `sourceCode`, `input`, `continueOnFailure`, `retryOnFailure`
* **LOOP\_ON\_ITEMS**: `loopItems`
* **ROUTER**: creates a router with Branch 1 + Otherwise
### ap\_update\_trigger
Set or update the trigger for a flow.
| Input | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `pieceName` | string | Yes | Piece name (e.g., `@activepieces/piece-gmail`) |
| `triggerName` | string | Yes | Trigger name from the piece |
| `input` | object | No | Trigger configuration |
| `auth` | string | No | Connection externalId |
| `displayName` | string | No | Display name for the trigger step |
### ap\_add\_step
Add a new step to a flow. Optionally configure it in the same call by providing `input`, `auth`, `sourceCode`, or `loopItems`.
| Input | Type | Required | Description |
| ------------------------------ | ------- | -------- | ----------------------------------------------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `parentStepName` | string | Yes | Step to insert after/into |
| `stepLocationRelativeToParent` | string | Yes | `AFTER`, `INSIDE_LOOP`, or `INSIDE_BRANCH` |
| `stepType` | string | Yes | `CODE`, `PIECE`, `LOOP_ON_ITEMS`, or `ROUTER` |
| `displayName` | string | Yes | Step display name |
| `pieceName` | string | No | For PIECE steps |
| `actionName` | string | No | For PIECE steps |
| `branchIndex` | number | No | For INSIDE\_BRANCH |
| `input` | object | No | Step input config (key-value pairs) |
| `auth` | string | No | Connection externalId |
| `sourceCode` | string | No | For CODE steps: JavaScript/TypeScript source |
| `packageJson` | string | No | For CODE steps: npm dependencies |
| `loopItems` | string | No | For LOOP steps: items expression |
| `continueOnFailure` | boolean | No | For CODE/PIECE steps: continue flow if this step fails (default: false) |
| `retryOnFailure` | boolean | No | For CODE/PIECE steps: retry this step on failure (default: false) |
### ap\_update\_step
Update an existing step's settings. Auto-fills default values for optional properties.
| Input | Type | Required | Description |
| ------------------- | ------- | -------- | ------------------------------------------------------ |
| `flowId` | string | Yes | The flow ID |
| `stepName` | string | Yes | Step name (e.g., `step_1`) |
| `displayName` | string | No | New display name |
| `input` | object | No | Step configuration |
| `auth` | string | No | Connection externalId |
| `actionName` | string | No | For PIECE steps |
| `loopItems` | string | No | For LOOP steps |
| `sourceCode` | string | No | For CODE steps: JavaScript/TypeScript source code |
| `packageJson` | string | No | For CODE steps: npm dependencies as JSON string |
| `skip` | boolean | No | Skip this step |
| `continueOnFailure` | boolean | No | For CODE/PIECE steps: continue flow if this step fails |
| `retryOnFailure` | boolean | No | For CODE/PIECE steps: retry this step on failure |
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.
### ap\_delete\_step
Delete a step from a flow.
| Input | Type | Required | Description |
| ---------- | ------ | -------- | -------------- |
| `flowId` | string | Yes | The flow ID |
| `stepName` | string | Yes | Step to delete |
***
## Router & Branching
Manage conditional branches in router steps. Use `ap_flow_structure` to see existing branch conditions and indices.
### ap\_add\_branch
Add a conditional branch to a router step. The branch is inserted before the fallback (Otherwise) branch.
| Input | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------- |
| `flowId` | string | Yes | The flow ID |
| `routerStepName` | string | Yes | The router step name |
| `branchName` | string | Yes | Display name for the branch |
| `conditions` | array | No | Conditions array (see below) |
**Conditions format:** Outer array = OR groups, inner array = AND conditions. Each condition has:
* `firstValue` (string) — left-hand value, can use `{{step_1.field}}` template syntax
* `operator` (string) — e.g. `TEXT_CONTAINS`, `NUMBER_IS_GREATER_THAN`, `EXISTS`, `BOOLEAN_IS_TRUE`
* `secondValue` (string, optional) — right-hand value (not needed for single-value operators)
* `caseSensitive` (boolean, optional) — for text operators
### ap\_update\_branch
Update the conditions and/or name of an existing router branch without affecting the steps inside it.
| Input | Type | Required | Description |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `routerStepName` | string | Yes | The router step name |
| `branchIndex` | number | Yes | Branch index (0-based) |
| `branchName` | string | No | New display name |
| `conditions` | array | No | New conditions (same format as `ap_add_branch`). Replaces existing conditions entirely. |
Cannot set conditions on the fallback branch — only `branchName` can be updated for fallback branches.
### ap\_delete\_branch
Delete a branch from a router step. Cannot delete the fallback (last) branch.
| Input | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `routerStepName` | string | Yes | The router step name |
| `branchIndex` | number | Yes | Branch index to delete (0-based) |
***
## Annotations
### ap\_manage\_notes
Add, update, or delete canvas notes on a flow.
| Input | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `operation` | string | Yes | `ADD`, `UPDATE`, or `DELETE` |
| `noteId` | string | No | Required for UPDATE/DELETE |
| `content` | string | No | Note text (required for ADD) |
| `color` | string | No | Note color |
| `position` | object | No | `{x, y}` canvas position |
| `size` | object | No | `{width, height}` note dimensions (default 200x200) |
***
## Tables
Full CRUD operations for the built-in Tables feature. Use field names (not IDs) when inserting or updating records.
### ap\_create\_table
Create a new table with an initial set of fields.
| Input | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------- |
| `name` | string | Yes | Table name |
| `fields` | array | Yes | Fields: `{name, type, options?}` |
**Field types:** `TEXT`, `NUMBER`, `DATE`, `STATIC_DROPDOWN` (requires `options` array)
### ap\_delete\_table
Permanently delete a table and all its data.
| Input | Type | Required | Description |
| --------- | ------ | -------- | ------------ |
| `tableId` | string | Yes | The table ID |
### ap\_manage\_fields
Add, rename, or delete fields on a table.
| Input | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------- |
| `tableId` | string | Yes | The table ID |
| `operation` | string | Yes | `ADD`, `UPDATE`, or `DELETE` |
| `fieldId` | string | No | Required for UPDATE/DELETE |
| `name` | string | No | Required for ADD/UPDATE |
| `type` | string | No | Required for ADD |
| `options` | array | No | For STATIC\_DROPDOWN |
### ap\_insert\_records
Insert one or more records into a table.
| Input | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| `tableId` | string | Yes | The table ID |
| `records` | array | Yes | 1-50 records, each mapping field names to values |
### ap\_update\_record
Update specific cells in a record. Only specified fields are changed.
| Input | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------- |
| `tableId` | string | Yes | The table ID |
| `recordId` | string | Yes | The record ID |
| `fields` | object | Yes | Field names to new values |
### ap\_delete\_records
Permanently delete one or more records.
| Input | Type | Required | Description |
| ----------- | ----- | -------- | -------------------- |
| `recordIds` | array | Yes | Record IDs to delete |
***
## Testing & Runs
Test flows, inspect results, and retry failures. Test tools poll for up to 120 seconds and return step-by-step results.
### ap\_test\_flow
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).
| Input | Type | Required | Description |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------- |
| `flowId` | string | Yes | The flow ID |
| `triggerTestData` | object | No | Mock trigger output data. Saved as sample data before running the test. |
The flow must have a configured trigger. The tool validates this before running and returns a clear error if not.
### ap\_test\_step
Test a single step within a flow. Runs all steps up to and including the target step. Pass `triggerTestData` when no sample data exists.
| Input | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------- |
| `flowId` | string | Yes | The flow ID |
| `stepName` | string | Yes | Step to test |
| `triggerTestData` | object | No | Mock trigger output data. |
### ap\_retry\_run
Retry a failed flow run.
| Input | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------- |
| `flowRunId` | string | Yes | The failed run ID |
| `strategy` | string | Yes | `FROM_FAILED_STEP` or `ON_LATEST_VERSION` |
* **FROM\_FAILED\_STEP**: Resume from where it failed, keeping previous step outputs
* **ON\_LATEST\_VERSION**: Re-run the entire flow with the current published version
### ap\_run\_action
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 tool creates a disposable flow, runs the action, returns the output, and cleans the flow up — the user never sees it in their flow list.
| Input | Type | Required | Description |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pieceName` | string | Yes | Piece name (e.g. `slack` or `@activepieces/piece-slack`). Use `ap_research_pieces` to discover. |
| `actionName` | string | Yes | Action to run (e.g. `send_channel_message`). Use `ap_get_piece_props` for the input shape. |
| `input` | object | No | Fully-resolved input for the action. Keys must match the piece action's props. Pass raw values — do **not** wrap them in `{{…}}`. Omit entirely if the action has no props. |
| `connectionExternalId` | string | No | `externalId` from `ap_list_connections`. Required if the piece needs auth. Auto-wrapped server-side as `{{connections['externalId']}}`. Must be a plain ID — special characters are rejected. |
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.