> 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

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-automations agent plugin** ([Gradient-Works/agent-plugins](https://github.com/Gradient-Works/agent-plugins)) provides the `gw-abk-actions` skill: 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

See the [agent-plugins README](https://github.com/Gradient-Works/agent-plugins) for installation instructions for Claude Code, Codex, and Cursor.

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 plugin 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.