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

## How the pieces fit together

**Salesforce** is where your flows live. The Gradient Works ABK actions 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gradient.works/kb/mcp/flow-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.