Activepieces MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'activepiecesmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Activepieces MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'activepiecesmcp_ap_change_flow_status',
     toolInput: { flowId: 'YOUR_FLOWID', status: 'YOUR_STATUS' },
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "activepiecesmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Activepieces MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={"flowId":"YOUR_FLOWID","status":"YOUR_STATUS"},
       tool_name="activepiecesmcp_ap_change_flow_status",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Branch ap add — Add a conditional branch to a router step
• Step ap add, ap test — Add a new step to a flow
• Flow ap build, ap duplicate, ap rename — Create a NEW flow from scratch in one call: trigger + steps
• Status ap change flow — Enable or disable a published flow
• Create ap — Create a new flow in Activepieces
• Delete ap — Delete a branch from a router step

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

activepiecesmcp_ap_add_branch#Add a conditional branch to a router step. Inserted before the fallback branch.4 params▾

Add a conditional branch to a router step. Inserted before the fallback branch.

NameTypeRequiredDescription

branchNamestringrequiredDisplay name for the new branch (e.g. "Branch 1")

flowIdstringrequiredThe id of the flow

routerStepNamestringrequiredThe name of the ROUTER step to add a branch to. Use ap_flow_structure to get valid values.

conditionsarrayoptionalConditions array (outer array = OR groups, inner array = AND conditions). Required for condition-type branches; omit to use an empty condition group.

activepiecesmcp_ap_add_step#Add a new step to a flow. Optionally configure it in the same call by providing input/auth/sourceCode. Prefer PIECE actions and inline formula expressions over CODE.15 params▾

Add a new step to a flow. Optionally configure it in the same call by providing input/auth/sourceCode. Prefer PIECE actions and inline formula expressions over CODE.

NameTypeRequiredDescription

displayNamestringrequiredDisplay name for the step

flowIdstringrequiredThe id of the flow

parentStepNamestringrequiredThe step name to insert after/into (e.g. "trigger", "step_1"). Use ap_flow_structure to get valid values.

stepLocationRelativeToParentstringrequiredWhere to place the step: AFTER = after the parent, INSIDE_LOOP = first action inside a loop, INSIDE_BRANCH = first action inside a router branch, INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH = first action inside the On success / On failure branch of a continue-on-failure step (set continueOnFailure on the parent first).

stepTypestringrequiredThe type of step to add. Prefer PIECE over CODE - only use CODE when no piece fits and the logic can't be done with an inline formula expression (in a free-text/value input) or a router condition.

actionNamestringoptionalFor PIECE steps: the action name within the piece. Use ap_research_pieces with includeActions=true to get valid values.

authstringoptionalConnection externalId from ap_list_connections. Auto-wrapped as {{connections['externalId']}}.

branchIndexnumberoptionalBranch index (required when stepLocationRelativeToParent is INSIDE_BRANCH)

continueOnFailurebooleanoptionalFor CODE/PIECE steps: set true on the step that can fail (the one whose failure you want to react to), NOT on the recovery step. Defaults to false. When true the flow keeps running on failure and the step gains On success / On failure branches - add handler steps into them with stepLocationRelativeToParent INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH and parentStepName = this step.

inputobjectoptionalFor PIECE/CODE steps: input config (key-value pairs). Reference a prior step's output with {{stepName['output'].field}} (output is nested under ['output'], e.g. {{trigger['output'].body.email}}, {{send_email['output'].id}}). For a continue-on-failure step's error, use {{stepName['error'].message}}.

loopItemsstringoptionalFor LOOP steps: expression for items to iterate (e.g. "{{step_1['output'].items}}").

packageJsonstringoptionalFor CODE steps: package.json as JSON string. Defaults to "{}".

pieceNamestringoptionalFor PIECE steps: the piece name (e.g. "@activepieces/piece-gmail"). Use ap_research_pieces to get valid values.

retryOnFailurebooleanoptionalFor CODE/PIECE steps: whether to retry this step on failure. Defaults to false.

sourceCodestringoptionalFor CODE steps: JavaScript/TypeScript source. Must export a code function.

activepiecesmcp_ap_build_flow#Create a NEW flow from scratch in one call: trigger + steps. Steps are added sequentially by default (trigger → step_1 → step_2 → ...). To nest steps inside a loop, set parentStepName to the loop step name and stepLocationRelativeToParent to INSIDE_LOOP. ROUTER steps are NOT supported here (branches and conditions cannot be configured in one call) — build the rest of the flow first, then add the router with ap_add_step and configure branches with ap_add_branch / ap_update_branch. For EDITING an existing flow, do NOT rebuild it — use the granular ap_add_step / ap_update_step / ap_update_trigger instead. Prefer PIECE actions and inline formula expressions (in a free-text/value input — never a dropdown/option field — wrapped `ap-formula-v1::{...}::ap-formula-v1`) over CODE steps — only emit a CODE step when no piece fits AND the logic exceeds the inline formula functions (see the build_flow guide expression ladder).3 params▾

Create a NEW flow from scratch in one call: trigger + steps. Steps are added sequentially by default (trigger → step_1 → step_2 → ...). To nest steps inside a loop, set parentStepName to the loop step name and stepLocationRelativeToParent to INSIDE_LOOP. ROUTER steps are NOT supported here (branches and conditions cannot be configured in one call) — build the rest of the flow first, then add the router with ap_add_step and configure branches with ap_add_branch / ap_update_branch. For EDITING an existing flow, do NOT rebuild it — use the granular ap_add_step / ap_update_step / ap_update_trigger instead. Prefer PIECE actions and inline formula expressions (in a free-text/value input — never a dropdown/option field — wrapped `ap-formula-v1::{...}::ap-formula-v1`) over CODE steps — only emit a CODE step when no piece fits AND the logic exceeds the inline formula functions (see the build_flow guide expression ladder).

NameTypeRequiredDescription

flowNamestringrequiredName for the new flow

stepsarrayrequiredArray of steps. By default added sequentially after trigger. Use parentStepName + stepLocationRelativeToParent to nest steps inside loops. Each step supports: PIECE (pieceName+actionName+input), CODE (sourceCode+input), LOOP_ON_ITEMS (loopItems). Prefer PIECE and inline formula expressions (in free-text/value inputs, not dropdowns) over CODE — reach for a CODE step only when no piece fits and the transform exceeds the inline formula functions. ROUTER is not supported here — add it afterwards with ap_add_step + ap_add_branch.

triggerobjectrequiredTrigger configuration: which piece and trigger to start the flow with, plus its input and auth.

activepiecesmcp_ap_change_flow_status#Enable or disable a published flow.2 params▾

Enable or disable a published flow.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

statusstringrequiredThe new status: ENABLED to activate the flow, DISABLED to pause it

activepiecesmcp_ap_create_flow#Create a new flow in Activepieces.1 param▾

Create a new flow in Activepieces.

NameTypeRequiredDescription

flowNamestringrequiredThe name of the flow

activepiecesmcp_ap_create_table#Create a new table with an initial set of fields. Types: TEXT, NUMBER, DATE, STATIC_DROPDOWN.2 params▾

Create a new table with an initial set of fields. Types: TEXT, NUMBER, DATE, STATIC_DROPDOWN.

NameTypeRequiredDescription

fieldsarrayrequiredFields to create. Max 100 fields per table.

namestringrequiredThe name of the table

activepiecesmcp_ap_delete_branch#Delete a branch from a router step. Cannot delete the fallback branch.4 params▾

Delete a branch from a router step. Cannot delete the fallback branch.

NameTypeRequiredDescription

branchIndexnumberrequiredThe index of the branch to delete (0-based). Cannot delete the fallback/last branch.

flowIdstringrequiredThe id of the flow

routerStepNamestringrequiredThe name of the ROUTER step. Use ap_flow_structure to get valid values.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Delete branch 2 from router"). Must include what the action does and the target name.

activepiecesmcp_ap_delete_flow#Permanently delete a flow and all its versions. This cannot be undone.1 param▾

Permanently delete a flow and all its versions. This cannot be undone.

NameTypeRequiredDescription

flowIdstringrequiredThe ID of the flow to delete

activepiecesmcp_ap_delete_records#Permanently delete one or more records by their IDs.2 params▾

Permanently delete one or more records by their IDs.

NameTypeRequiredDescription

recordIdsarrayrequiredArray of record IDs to delete. Use ap_find_records to find them.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Delete 3 records from Emails table"). Must include what the action does and the target name.

activepiecesmcp_ap_delete_step#Delete a step from a flow. Prefer ap_update_step to modify - delete destroys sample data.3 params▾

Delete a step from a flow. Prefer ap_update_step to modify - delete destroys sample data.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

stepNamestringrequiredThe name of the step to delete. Use ap_flow_structure to get valid values.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Delete Send Email step"). Must include what the action does and the target name.

activepiecesmcp_ap_delete_table#Permanently delete a table and all its data.2 params▾

Permanently delete a table and all its data.

NameTypeRequiredDescription

tableIdstringrequiredThe ID of the table to delete. Use ap_list_tables to find it.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Delete Customer Emails table"). Must include what the action does and the target name.

activepiecesmcp_ap_duplicate_flow#Duplicate an existing flow. Creates a new copy with all steps and configuration. Connections and sample data are not copied.2 params▾

Duplicate an existing flow. Creates a new copy with all steps and configuration. Connections and sample data are not copied.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow to duplicate. Use ap_list_flows to find it.

namestringoptionalName for the duplicated flow. Defaults to "Copy of {original name}".

activepiecesmcp_ap_find_records#Query records from a table with optional filtering. Operators: eq, neq, gt, gte, lt, lte, co, exists, not_exists.3 params▾

Query records from a table with optional filtering. Operators: eq, neq, gt, gte, lt, lte, co, exists, not_exists.

NameTypeRequiredDescription

tableIdstringrequiredThe table ID. Use ap_list_tables to find it.

filtersarrayoptionalOptional filters. All filters are combined with AND logic.

limitnumberoptionalMax records to return (default 50, max 500)

activepiecesmcp_ap_flow_structure#Get the structure of a flow: step tree (parent/child), each step type, configuration status (configured/unconfigured/invalid), and valid insert locations for ap_add_step.1 param▾

Get the structure of a flow: step tree (parent/child), each step type, configuration status (configured/unconfigured/invalid), and valid insert locations for ap_add_step.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

activepiecesmcp_ap_get_piece_props#Get the input schema for a piece action or trigger, plus AI guidance for using it: an AI-written description of what it does, an idempotency hint, and — when available — the output field paths it produces (for triggers, also derived from sample data). Use the AI description to pick the right action; when output fields are listed, reference them directly downstream as {{step['output'].path}}. Pass auth to resolve dynamic dropdowns and dynamic property sub-fields (e.g. Custom API Call url/body fields).6 params▾

Get the input schema for a piece action or trigger, plus AI guidance for using it: an AI-written description of what it does, an idempotency hint, and — when available — the output field paths it produces (for triggers, also derived from sample data). Use the AI description to pick the right action; when output fields are listed, reference them directly downstream as {{step['output'].path}}. Pass auth to resolve dynamic dropdowns and dynamic property sub-fields (e.g. Custom API Call url/body fields).

NameTypeRequiredDescription

actionOrTriggerNamestringrequiredThe action or trigger name (e.g. "send_channel_message"). Use ap_research_pieces with pieceNames to get valid values.

pieceNamestringrequiredThe piece name (e.g. "@activepieces/piece-slack"). Use ap_research_pieces to get valid values.

typestringrequiredWhether to look up an action or a trigger.

authstringoptionalConnection externalId from ap_list_connections. When provided, dynamic dropdowns and dynamic property sub-fields are resolved via your account.

flowIdstringoptionalFlow ID for resolving dependent dropdowns that need step context. Optional — most dropdowns work without it.

inputobjectoptionalKnown input values to resolve dependent dynamic properties.

activepiecesmcp_ap_get_run#Get detailed results of a flow run including step-by-step outputs, errors, and durations.1 param▾

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

NameTypeRequiredDescription

flowRunIdstringrequiredThe ID of the flow run. Use ap_list_runs to find it.

activepiecesmcp_ap_insert_records#Insert one or more records into a table. Max 50 records per call.2 params▾

Insert one or more records into a table. Max 50 records per call.

NameTypeRequiredDescription

recordsarrayrequiredArray of records (1-50). Each record maps field names to values. Example: [{"Name": "Alice", "Age": "30"}]

tableIdstringrequiredThe table ID (the "id" from ap_list_tables; the externalId is also accepted).

activepiecesmcp_ap_list_ai_models#List configured AI providers and their available models. Use this to discover valid provider and model values for configuring Run Agent steps. The output shows provider names and model IDs needed for the aiProviderModel input.1 param▾

List configured AI providers and their available models. Use this to discover valid provider and model values for configuring Run Agent steps. The output shows provider names and model IDs needed for the aiProviderModel input.

NameTypeRequiredDescription

providerstringoptionalFilter by provider name. Omit to list all configured providers and their models.

activepiecesmcp_ap_list_connections#List OAuth/app connections in the project. Returns externalId needed for the auth parameter on steps.3 params▾

List OAuth/app connections in the project. Returns externalId needed for the auth parameter on steps.

NameTypeRequiredDescription

displayNamestringoptionalFilter by connection display name (partial, case-insensitive match). Use to find a connection by its label, e.g. "My Gmail" or "Slack workspace".

pieceNamestringoptionalFilter by piece name. Short names like "slack" or "google-drive" are auto-expanded to full format (e.g. "@activepieces/piece-slack"). You can also pass the full name directly.

statusarrayoptionalFilter by status: ACTIVE (working), MISSING (deleted or inaccessible), ERROR (auth/refresh failed). Omit to return all statuses.

activepiecesmcp_ap_list_flows#List flows in the current project with status, trigger type, and published state.3 params▾

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

NameTypeRequiredDescription

limitintegeroptionalMax flows to return (default 100, max 500).

namestringoptionalFilter by flow name (partial match).

statusstringoptionalFilter by status: ENABLED or DISABLED.

activepiecesmcp_ap_list_runs#List recent flow runs with optional filters. Returns run ID, status, timestamps, and failed step info.4 params▾

List recent flow runs with optional filters. Returns run ID, status, timestamps, and failed step info.

NameTypeRequiredDescription

environmentstringoptionalFilter by environment: PRODUCTION (live runs) or TESTING (manual test runs). Defaults to PRODUCTION when no flowId is given, since cross-environment scans on the runs table are slow.

flowIdstringoptionalFilter by flow ID. Use ap_list_flows to find it.

limitnumberoptionalMax runs to return (default 10, max 50)

statusstringoptionalFilter by status: SUCCEEDED, FAILED, RUNNING, QUEUED, PAUSED, TIMEOUT, etc.

activepiecesmcp_ap_list_tables#List all tables in the current project with their fields (name, type, id) and row counts. Use this to discover available tables before querying or modifying data. Each table has two ids: use "id" with the record/field MCP tools (ap_insert_records, ap_find_records, ap_manage_fields, etc.), and use "externalId" as the table_id value when configuring a Tables piece step inside a flow.0 params▾

List all tables in the current project with their fields (name, type, id) and row counts. Use this to discover available tables before querying or modifying data. Each table has two ids: use "id" with the record/field MCP tools (ap_insert_records, ap_find_records, ap_manage_fields, etc.), and use "externalId" as the table_id value when configuring a Tables piece step inside a flow.

activepiecesmcp_ap_lock_and_publish#Publish and enable the current draft version of a flow. This locks the draft, sets it as the published version, and enables the flow. Returns validation errors if the flow is not ready.1 param▾

Publish and enable the current draft version of a flow. This locks the draft, sets it as the published version, and enables the flow. Returns validation errors if the flow is not ready.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow to publish

activepiecesmcp_ap_manage_fields#Add, rename, or delete fields on a table. Max 100 fields per table.6 params▾

Add, rename, or delete fields on a table. Max 100 fields per table.

NameTypeRequiredDescription

operationstringrequiredADD a new field, UPDATE (rename) an existing field, or DELETE a field

tableIdstringrequiredThe table ID

fieldIdstringoptionalThe field ID (required for UPDATE and DELETE). Use ap_list_tables to find it.

namestringoptionalField name (required for ADD and UPDATE)

optionsarrayoptionalDropdown options (required for ADD with STATIC_DROPDOWN type)

typestringoptionalField type (required for ADD only)

activepiecesmcp_ap_manage_notes#Add, update, or delete canvas notes on a flow. Notes are visual annotations on the flow canvas.7 params▾

Add, update, or delete canvas notes on a flow. Notes are visual annotations on the flow canvas.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

operationstringrequiredOperation to perform: ADD a new note, UPDATE an existing note, or DELETE a note

colorstringoptionalNote color variant (orange, red, green, blue, purple, yellow). Default: yellow

contentstringoptionalThe text content of the note (required for ADD, optional for UPDATE)

noteIdstringoptionalThe note ID (required for UPDATE and DELETE)

positionobjectoptionalPosition on the canvas (required for ADD, optional for UPDATE)

sizeobjectoptionalSize of the note (optional, defaults to 200x200)

activepiecesmcp_ap_read_step_code#Read the full source code, package.json, and input of a CODE step. Returns untruncated content (unlike ap_flow_structure which truncates).2 params▾

Read the full source code, package.json, and input of a CODE step. Returns untruncated content (unlike ap_flow_structure which truncates).

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

stepNamestringrequiredThe name of the CODE step (e.g. "step_1"). Use ap_flow_structure to get valid values.

activepiecesmcp_ap_rename_flow#Rename a flow.2 params▾

Rename a flow.

NameTypeRequiredDescription

displayNamestringrequiredThe new display name for the flow

flowIdstringrequiredThe id of the flow to rename

activepiecesmcp_ap_research_pieces#Research available pieces. Use pieceNames for bulk exact lookup (always returns actions and triggers, each with an AI guidance hint). Use searchQuery for fuzzy discovery. Pass forIntent with what you are trying to do to get recommendedActions ranked by AI guidance, so you pick the right action in one shot.9 params▾

Research available pieces. Use pieceNames for bulk exact lookup (always returns actions and triggers, each with an AI guidance hint). Use searchQuery for fuzzy discovery. Pass forIntent with what you are trying to do to get recommendedActions ranked by AI guidance, so you pick the right action in one shot.

NameTypeRequiredDescription

categoriesarrayoptionalNo description.

forIntentstringoptionalWhat you are trying to do (e.g. "list all my open deals"). When set, each piece also returns recommendedActions — the actions whose AI guidance best matches your intent — so you can pick the right action in one shot. Advisory only; the full action list is always returned.

includeActionsbooleanoptionalWhen true, include action names and descriptions for each piece (only applies to searchQuery mode)

includeTriggersbooleanoptionalWhen true, include trigger names and descriptions for each piece (only applies to searchQuery mode)

localestringoptionalNo description.

pieceNamesarrayoptionalExact piece names to look up (e.g. ["gmail", "slack", "@activepieces/piece-google-sheets"]). Always returns actions and triggers for each piece.

searchQuerystringoptionalNo description.

suggestionTypestringoptionalNo description.

tagsarrayoptionalNo description.

activepiecesmcp_ap_resolve_property_chain#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. Always use the value from returned options, not the label.6 params▾

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. Always use the value from returned options, not the label.

NameTypeRequiredDescription

actionOrTriggerNamestringrequiredThe action or trigger name (e.g. "insert_row").

authstringrequiredConnection externalId - required to resolve options from the user's account.

pieceNamestringrequiredThe piece name (e.g. "@activepieces/piece-google-sheets").

propertyChainarrayrequiredOrdered list of properties to resolve (max 10). Each property is resolved using the values of all prior properties as context.

typestringrequiredWhether this is an action or trigger.

currentInputobjectoptionalAdditional input values already known (e.g. from prior configuration).

activepiecesmcp_ap_resolve_property_options#Resolve dropdown options for a single piece property. Returns the available options with labels and values (IDs). Use this to discover valid values for DROPDOWN fields (e.g. Slack channels, Google Sheets, email labels). Always use the `value` from the returned options, not the `label`.7 params▾

Resolve dropdown options for a single piece property. Returns the available options with labels and values (IDs). Use this to discover valid values for DROPDOWN fields (e.g. Slack channels, Google Sheets, email labels). Always use the `value` from the returned options, not the `label`.

NameTypeRequiredDescription

actionOrTriggerNamestringrequiredThe action or trigger name (e.g. "send_channel_message").

pieceNamestringrequiredThe piece name (e.g. "@activepieces/piece-slack").

propertyNamestringrequiredThe exact property name to resolve options for (e.g. "channel").

typestringrequiredWhether this is an action or trigger.

authstringoptionalConnection externalId. Required for pieces that resolve options from a connected account (e.g. Slack channels, Gmail labels). Omit for pieces that have no auth (e.g. Tables table_id) — passing a value there is unnecessary.

inputobjectoptionalValues for parent properties that this field depends on (refreshers).

searchValuestringoptionalSearch/filter term to narrow results for large dropdown lists (e.g., "sales" to find sales-related channels).

activepiecesmcp_ap_retry_run#Retry a failed flow run. FROM_FAILED_STEP resumes at failure point, ON_LATEST_VERSION re-runs entirely.2 params▾

Retry a failed flow run. FROM_FAILED_STEP resumes at failure point, ON_LATEST_VERSION re-runs entirely.

NameTypeRequiredDescription

flowRunIdstringrequiredThe ID of the failed flow run to retry. Use ap_list_runs to find it.

strategystringrequiredFROM_FAILED_STEP to resume where it failed, ON_LATEST_VERSION to re-run with the current published flow.

activepiecesmcp_ap_run_action#Execute a single piece action once, without building or saving a flow. Use this for one-shot tasks like "check my inbox" or "send one Slack message". For recurring/triggered work, build a flow with ap_build_flow instead.4 params▾

Execute a single piece action once, without building or saving a flow. Use this for one-shot tasks like "check my inbox" or "send one Slack message". For recurring/triggered work, build a flow with ap_build_flow instead.

NameTypeRequiredDescription

actionNamestringrequiredAction to run, e.g. "send_channel_message". Use ap_get_piece_props for the input shape.

pieceNamestringrequiredPiece name, e.g. "slack" or "@activepieces/piece-slack". Use ap_research_pieces to discover.

connectionExternalIdstringoptionalexternalId from ap_list_connections. Required if the piece needs auth. Auto-wrapped as {{connections['externalId']}}.

inputobjectoptionalFully-resolved input for the action. Keys must match the piece action's props. Pass raw values - do NOT wrap in {{...}}. Omit if the action has no props.

activepiecesmcp_ap_setup_guide#Get setup instructions for connections or AI providers. Returns steps for the user to follow in the UI.2 params▾

Get setup instructions for connections or AI providers. Returns steps for the user to follow in the UI.

NameTypeRequiredDescription

topicstringrequiredWhat to get setup instructions for

pieceNamestringoptionalFor connections: the piece that needs auth (e.g., "@activepieces/piece-gmail"). Omit for general instructions.

activepiecesmcp_ap_test_flow#Test a flow end-to-end in the test environment. Requires a configured trigger. Waits up to 120s. Pass triggerTestData to provide mock trigger output when no sample data exists.3 params▾

Test a flow end-to-end in the test environment. Requires a configured trigger. Waits up to 120s. Pass triggerTestData to provide mock trigger output when no sample data exists.

NameTypeRequiredDescription

flowIdstringrequiredThe ID of the flow to test. Use ap_list_flows to find it.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Test Send Welcome Email"). Must include what the action does and the target name.

triggerTestDataobjectoptionalMock trigger output data. Saved as sample data before running the test. Useful when the trigger has no prior test data.

activepiecesmcp_ap_test_step#Test a single step within a flow. Runs all steps up to and including the specified step. The flow must have a configured trigger. Pass triggerTestData when no sample data exists.4 params▾

Test a single step within a flow. Runs all steps up to and including the specified step. The flow must have a configured trigger. Pass triggerTestData when no sample data exists.

NameTypeRequiredDescription

flowIdstringrequiredThe ID of the flow containing the step. Use ap_list_flows to find it.

stepNamestringrequiredThe name of the step to test (e.g., "step_1"). Use ap_flow_structure to find it.

displayNamestringoptionalShort approval prompt shown to the user (e.g. "Test Send Email step in Welcome Flow"). Must include what the action does and the target name.

triggerTestDataobjectoptionalMock trigger output data. Saved as sample data before running the test. Useful when the trigger has no prior test data.

activepiecesmcp_ap_update_branch#Update the conditions and/or name of an existing router branch. Does not affect the steps inside the branch.5 params▾

Update the conditions and/or name of an existing router branch. Does not affect the steps inside the branch.

NameTypeRequiredDescription

branchIndexnumberrequiredThe index of the branch to update (0-based). Cannot update the fallback branch conditions.

flowIdstringrequiredThe id of the flow

routerStepNamestringrequiredThe name of the ROUTER step. Use ap_flow_structure to get valid values.

branchNamestringoptionalNew display name for the branch

conditionsarrayoptionalNew conditions array (outer array = OR groups, inner array = AND conditions). Replaces the existing conditions entirely.

activepiecesmcp_ap_update_record#Update specific cells in a record. Only specified fields are changed.3 params▾

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

NameTypeRequiredDescription

fieldsobjectrequiredObject mapping field names to new values. Only specified fields are updated. Example: {"Name": "Bob", "Age": "25"}

recordIdstringrequiredThe record ID to update. Use ap_find_records to find it.

tableIdstringrequiredThe table ID.

activepiecesmcp_ap_update_step#Update an existing step's settings. Provide only the fields you want to change.12 params▾

Update an existing step's settings. Provide only the fields you want to change.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

stepNamestringrequiredThe name of the step to update (e.g. "step_1"). Use ap_flow_structure to get valid values.

actionNamestringoptionalFor PIECE steps: the action to perform. Use ap_research_pieces to get valid values.

authstringoptionalConnection externalId from ap_list_connections. The tool wraps it automatically as {{connections['externalId']}}.

continueOnFailurebooleanoptionalFor CODE/PIECE steps: set true on the step that can fail (the one whose failure you want to react to), NOT on the recovery step. The flow keeps running on failure and the step gains On success / On failure branches - add handler steps into them with ap_add_step using stepLocationRelativeToParent INSIDE_ON_SUCCESS_BRANCH / INSIDE_ON_FAILURE_BRANCH and parentStepName = this step.

displayNamestringoptionalNew display name for the step

inputobjectoptionalInput settings for the step (key-value pairs matching the action schema). Reference a prior step's output with {{stepName['output'].field}} (output is nested under ['output'], e.g. {{trigger['output'].body.email}}, {{send_email['output'].id}}). For a continue-on-failure step's error, use {{stepName['error'].message}}.

loopItemsstringoptionalFor LOOP steps: expression for the items to iterate over

packageJsonstringoptionalFor CODE steps only: package.json content as a JSON string for npm dependencies. Defaults to "{}".

retryOnFailurebooleanoptionalFor CODE/PIECE steps: whether to retry this step on failure.

skipbooleanoptionalWhether to skip this step during execution

sourceCodestringoptionalFor CODE steps only: the JavaScript/TypeScript source code. Must export a code function: export const code = async (inputs) => { ... }.

activepiecesmcp_ap_update_trigger#Set or update the trigger for a flow.6 params▾

Set or update the trigger for a flow.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow

pieceNamestringrequiredThe piece name for the trigger (e.g. "@activepieces/piece-gmail"). Use ap_research_pieces to get valid values.

triggerNamestringrequiredThe trigger name within the piece (e.g. "new_email"). Use ap_research_pieces with includeTriggers=true to get valid values.

authstringoptionalConnection externalId from ap_list_connections. The tool wraps it automatically as {{connections['externalId']}}.

displayNamestringoptionalDisplay name for the trigger step

inputobjectoptionalInput settings for the trigger (key-value pairs). Reference a prior step's output with {{stepName['output'].field}} (output is nested under ['output'], e.g. {{trigger['output'].body.email}}, {{send_email['output'].id}}). For a continue-on-failure step's error, use {{stepName['error'].message}}.

activepiecesmcp_ap_validate_flow#Validate a flow for structural issues without publishing. Checks step validity, template references, and empty branches. Returns a detailed report with all issues found. Use this before ap_lock_and_publish to catch problems early.1 param▾

Validate a flow for structural issues without publishing. Checks step validity, template references, and empty branches. Returns a detailed report with all issues found. Use this before ap_lock_and_publish to catch problems early.

NameTypeRequiredDescription

flowIdstringrequiredThe id of the flow to validate. Use ap_list_flows to find it.

activepiecesmcp_ap_validate_step_config#Validate a step configuration before applying it. Returns field-level errors without modifying any flow. Use this to check your config is correct before calling ap_update_step or ap_update_trigger.10 params▾

Validate a step configuration before applying it. Returns field-level errors without modifying any flow. Use this to check your config is correct before calling ap_update_step or ap_update_trigger.

NameTypeRequiredDescription

stepTypestringrequiredThe type of step to validate.

actionNamestringoptionalFor PIECE_ACTION: action name (e.g. "send_channel_message").

authstringoptionalFor PIECE steps requiring auth: any non-empty string indicates auth is provided.

inputobjectoptionalFor PIECE_ACTION/PIECE_TRIGGER: the input config to validate (key-value pairs).

loopItemsstringoptionalFor LOOP_ON_ITEMS: expression for items to iterate over.

packageJsonstringoptionalFor CODE: package.json content as JSON string.

pieceNamestringoptionalFor PIECE_ACTION/PIECE_TRIGGER: piece name (e.g. "slack" or "@activepieces/piece-slack").

settingsobjectoptionalFor ROUTER: raw router settings including branches and executionType.

sourceCodestringoptionalFor CODE: the JavaScript/TypeScript source code.

triggerNamestringoptionalFor PIECE_TRIGGER: trigger name (e.g. "new_mention").