> For the complete documentation index, see [llms.txt](https://docs.gradient.works/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gradient.works/kb/mcp/flow-tools.md).

# Flow Tools

Read and edit Salesforce flows using the Gradient Works MCP and agent plugin

The Gradient Works MCP exposes tools for reading and editing Salesforce flows directly from an AI assistant. This page explains how the different pieces — Salesforce, the Gradient Works platform, the MCP server, and the agent plugin — fit together, and what you need to set up before making flow changes through an AI.

## When to use these tools

The flow tools are relevant for use cases where you need to create or edit assignment Flows that use Gradient Works [ABK actions](/kb/automation-builder-kit-abk/actions.md).

These tools allow an AI agent to build assignment-based flows — such as lead routing — with the assignment features provided by the [Gradient Works Routing product](/kb/routing/overview.md). Using a generic Salesforce MCP alone will let an agent build flows, but those flows won't use the Gradient Works actions.

## How the pieces fit together

**Salesforce** is where your flows live. The Gradient Works [ABK actions](/kb/automation-builder-kit-abk/actions.md) are installed in your org as part of the Gradient Works Salesforce package and appear as invocable actions inside Flow Builder. Flow metadata — elements, variables, action configurations — is read and written via Salesforce APIs.

**app.gradient.works** manages the connection between your AI assistant and Salesforce. A CRM connection configured in Gradient Works authenticates to your Salesforce org. Every MCP flow tool uses this connection and takes a `crm_connection_id` to identify which org to target. Use the `list_crm_connections` tool to find your connection's UUID.

**The MCP server** (`https://agents.gradient.works/mcp`) exposes the flow tools your AI assistant calls — listing flows, reading version metadata, saving new versions, activating, and deactivating. See [MCP setup](/kb/mcp/setup_claude.md) for instructions on connecting your AI client.

**The** [**`gw-abk-actions` skill**](https://github.com/Gradient-Works/agent-plugins/blob/main/plugins/gradient-works/skills/gw-abk-actions/SKILL.md) provides reference documentation for every Gradient Works ABK invocable action. When your AI builds or edits a flow that uses GW actions, this skill supplies authoritative input/output specs so it can configure action nodes correctly without guessing. See [Agent plugin](#agent-plugin) below for installation.

## Required Salesforce permissions

The Salesforce user authenticated in your Gradient Works CRM connection must have the following permissions:

* **Manage Flow** — required to create, edit, activate, and deactivate flows
* **Modify All Data** or **Modify Metadata Through Metadata API Functions** — required by the Salesforce Metadata API for any write operation
* **View All Data** — not strictly required, but without it activation may fail for certain flow types such as record-triggered autolaunched flows

## MCP flow tools

### Reading flows

| Tool                 | Description                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `list_flows`         | List flow definitions in the org. Filter by active status, process type, trigger object, or label search.                        |
| `get_flow`           | Get a single flow definition by its DurableId.                                                                                   |
| `list_flow_versions` | List all versions of a flow, ordered by version number descending, with status for each (Active, Draft, Obsolete, InvalidDraft). |
| `get_flow_version`   | Get the full metadata for a specific flow version. Null fields and empty lists are stripped by default for a cleaner result.     |

### Creating and editing flows

| Tool                  | Description                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_flow`         | Create a new flow definition. Returns the DurableId of the new flow.                                                                        |
| `create_flow_version` | Create a new draft version of an existing flow. Fetch the current metadata with `get_flow_version`, modify it, then submit the full object. |
| `update_flow_version` | Update an existing **Draft** version in place. Requires the complete metadata — not just changed fields. Active versions cannot be edited.  |

### Activating and deactivating

| Tool                      | Description                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `activate_flow_version`   | Set a version as the active version of the flow. The previously active version becomes Obsolete. |
| `deactivate_flow_version` | Clear the active version of a flow. The current active version becomes Obsolete.                 |

## Agent plugin

The [Gradient Works plugin](https://github.com/Gradient-Works/agent-plugins) includes the `gw-abk-actions` skill and configures the Gradient Works MCP. Paste the following text into your agent:

```
Can you help me set up Gradient Works by following this guide?
https://github.com/Gradient-Works/agent-plugins/blob/main/GETTING_STARTED.md
```

To install it yourself, follow the client-specific instructions in the [agent-plugins README](https://github.com/Gradient-Works/agent-plugins/blob/main/README.md).

Once installed, the AI can look up action specs while working with flow metadata. For example, when a `get_flow_version` response contains a `GradientWorks__AssignSingleItemAction` element, the skill tells the AI what each input field means, what types the outputs carry, and how to wire outputs from one action into inputs of the next.