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

# Frends MCP Tools

Tools available for AI Clients.

Frends MCP serves its operations as MCP Tools. A client sees only the Tools its token's scopes allow, so the list returned by `tools/list` is usually shorter than the full set described here.

Every table below names the scope each Tool needs, per Tool rather than per group. Read that column before granting a token: the scopes do not follow the groupings a reader might expect, and `validate_process` in particular needs only read access.

{% hint style="info" %}
Frends MCP is available from Frends version 6.3.2 onwards.
{% endhint %}

## Notes regarding the Tools <a href="#before-the-tables" id="before-the-tables"></a>

#### A Draft is not a Process

The authoring Tools all work on a Process Draft. A Draft is invisible to Agents and nothing runs from it.

#### Creating a Process from a Draft deploys it to Development

`create_process_from_draft` compiles the Draft into a new Process version **and deploys that version to the development Agent Group in the same call**. Whether its triggers become reachable is controlled by the `activate` flag on that same call. There is no separate activation Tool.

#### Processes are automatically versioned

Saving a new Process version does not overwrite or destroy the earlier Process versions. It is simply added to the built-in version management as the latest version. The older version can be restored to use at any time from the Frends UI.

#### Deployed and Active are two independent states

Deployed means the version is present on the Agent. Active means its triggers are enabled and reachable. A Process can be deployed and inactive. For a brand-new Process, omitting `activate` on the promote call leaves it inactive; when the Draft edits an existing Process, omitting the flag keeps that Process's current activation state.

#### Some Tools write outside the authoring group

`create_environment_variable` creates a real Environment Variable, and `import_task` installs a Task package into the Tenant. Both are writes, and both sit outside the authoring section. Grant `environment_variable:edit` and `task:edit` deliberately.

{% hint style="warning" %}
**Process Variables cannot be set or edited through these Tools.** Build the Draft with the Tools, then add its Process Variables in the Process editor. `get_process_data` returns them for reading; nothing here writes them.
{% endhint %}

## Tool list in Frends Tenant

## Orientation <a href="#orientation" id="orientation"></a>

`get_overview` is the usual first call. These three need an authenticated token but **no scope**.

| Tool           | What it does                                                                                                                                                           | Scope |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| `get_overview` | Returns an overview of the Tenant: Frends version, Environments, Agent Groups, counts of Processes, Tasks and Environment Variables, and the available FrendsAi models | none  |
| `list_guides`  | Lists the available guides                                                                                                                                             | none  |
| `get_guide`    | Returns one guide by name                                                                                                                                              | none  |

A client should read the relevant guide before authoring or diagnosing anything. The guide carries the platform's order of operations, which the Tool list on its own does not.

## Exploring Processes <a href="#exploring-processes" id="exploring-processes"></a>

Tools for exploring Processes in your Frends Tenant.

<table data-search="false"><thead><tr><th>Tool</th><th>What it does</th><th>Scope</th></tr></thead><tbody><tr><td><code>list_processes</code></td><td>Lists Processes deployed to at least one Agent Group. Returns one entry per Process and Agent Group pair, each with a <code>deploymentId</code>, which is the identifier <code>start_process</code> and <code>deploy_process</code> take. Paginated, and filterable on the server by name, Agent Group, trigger type and Task, so a client can narrow a large Tenant before reading anything in detail</td><td><code>process:view</code></td></tr><tr><td><code>list_process_drafts</code></td><td>Lists the Process Drafts in the Tenant. A Draft may be new, or an edit-draft of an already-promoted Process, in which case it carries that Process's GUID</td><td><code>process:view</code></td></tr><tr><td><code>get_process_data</code></td><td>Returns the full data model of one Draft or deployed Process: BPMN XML, element parameters, Process Variables and manual trigger configuration</td><td><code>process:view</code></td></tr><tr><td><code>process_get_structure</code></td><td>Returns the structural outline of a Draft: shapes with their ids, types, selected Task type ids, nested children for scopes, and outgoing connections</td><td><code>process:view</code></td></tr><tr><td><code>process_get_shape_config</code></td><td>Returns the full element-parameter configuration of a single shape</td><td><code>process:view</code></td></tr><tr><td><code>validate_process</code></td><td>Checks whether a Draft compiles and is structurally valid, and returns the problems found. <strong>This is a read: it needs only</strong> <code>process:view</code> <strong>and it saves nothing</strong></td><td><code>process:view</code></td></tr></tbody></table>

Call `validate_process` repeatedly while authoring rather than once at the end.

## **Narrowing the Process list**

On a Tenant with many Processes, reading them one by one is the wrong approach. `list_processes` filters on the server, and the filters combine, so a client should narrow first and read detail second.

| Filter              | Matches                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nameFilter`        | Part of the Process name, case-insensitive                                                                                                                          |
| `agentGroupFilter`  | An Agent Group, exactly                                                                                                                                             |
| `triggerTypeFilter` | The start of a trigger type, case-insensitive, for example `HttpTrigger` or `ScheduleTrigger`. Returns Processes with at least one trigger of that type             |
| `taskFilter`        | Part of a Task name, display name or package id, for example `Frends.HTTP` or `HTTP Request`. Returns Processes that use at least one matching Task, in any version |

Results are paged with `page` and `pageSize`, where `pageSize` is at most 100 and defaults to 20, and the response carries `totalCount` so a client knows whether to ask for more.

{% hint style="info" %}
A `taskFilter` that matches more than 25 Tasks is rejected with an error rather than returning a very large result. A bare vendor prefix such as `Frends` will fail for that reason. Use `list_tasks` to find the exact Task name or package id first, then filter on that.
{% endhint %}

Tags are not a server-side filter. A client that needs to filter by tag reads the Processes first and filters the results itself.

## Working with Tasks <a href="#working-with-tasks" id="working-with-tasks"></a>

Tools related to managing and searching available Tasks in Frends Tenant.

| Tool                   | What it does                                                                                                            | Scope       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- |
| `list_tasks`           | Lists the installed Frends Task methods                                                                                 | `task:view` |
| `search_task_packages` | Searches the configured NuGet feeds for Task packages available to import                                               | `task:view` |
| `inspect_task`         | Returns one Task's parameters and their types, which is what a client needs before it can configure that Task correctly | `task:view` |
| `import_task`          | Downloads a Task package from the configured feeds and **installs it into the Tenant**. This is a write                 | `task:edit` |

## Environment Variables <a href="#environment-variables" id="environment-variables"></a>

Tools for viewing and creating Environment Variables.

| Tool                          | What it does                                                                                                                                         | Scope                       |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `list_environment_variables`  | Lists the Environment Variable groups defined in the Tenant, so a client can reference an existing value instead of writing a literal into a Process | `environment_variable:view` |
| `create_environment_variable` | **Creates** a new Environment Variable inside a variable group. If the group does not exist it is created too                                        | `environment_variable:edit` |

## Authoring a Process <a href="#authoring-a-process" id="authoring-a-process"></a>

Authoring happens on a Draft, so a client can build and re-validate freely without affecting anything that runs. Every Tool in this section needs `process:edit`.

### Draft lifecycle

Tools for initializing a Process Draft, and saving a Draft as new Process version.

| Tool                        | What it does                                                                                                                                                                                                                                                                        | Scope          |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `create_process_draft`      | Creates a new Process Draft                                                                                                                                                                                                                                                         | `process:edit` |
| `create_process_from_draft` | Compiles a validated Draft into a Process version **and deploys it to the development Agent Group**. Pass `activate: true` to make a non-manual trigger reachable. Omitting it leaves a new Process deployed but inactive, and keeps an existing Process's current activation state | `process:edit` |

{% hint style="info" %}
A token holding only `process:edit` can therefore put a compiled Process onto the development Agent Group. Deploying to any other Agent Group is a separate `deploy_process` call and needs `process:deploy`.
{% endhint %}

### Adding a Trigger

A Trigger decides how a Process starts. If a Process uses more than one Trigger, every Trigger must connect to the same shape.

<table data-search="false"><thead><tr><th>Tool</th><th>What it does</th><th>Scope</th></tr></thead><tbody><tr><td><code>process_add_manual_trigger</code></td><td>Adds a manual start event: the Process is invoked on demand, and the InputParameters become its Process-level inputs</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_http_trigger</code></td><td>Adds an HTTP start event: the Process is invoked over HTTP when a request hits its route</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_schedule_trigger</code></td><td>Adds a time-based start event: the Process runs at configured times, with optional recurrence, cycle and season settings</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_conditional_trigger</code></td><td>Adds a conditional start event: the Process fires on a polling interval, but only when a designated precondition subprocess returns true</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_file_watch_trigger</code></td><td>Adds a file-watch start event: the Process fires when files matching a mask appear in a watched directory</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_mcp_trigger</code></td><td>Adds an MCP start event: the Process is exposed as an MCP tool that an AI model can invoke directly</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_queue_trigger</code></td><td>Adds an AMQP 1.0 queue start event, addressed by its bus URI, for example an Azure Service Bus queue or topic over AMQP</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_service_bus_trigger</code></td><td>Adds an Azure Service Bus start event: the Process runs for each message received from a queue or topic</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_rabbitmq_trigger</code></td><td>Adds a RabbitMQ start event: the Process runs for each message consumed from a queue</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_tcp_trigger</code></td><td>Adds a TCP start event: the Process is invoked when a TCP message arrives on the configured address and port</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_azure_event_hub_trigger</code></td><td>Adds an Azure Event Hub start event: the Process is invoked for each batch of events received from the configured Event Hub</td><td><code>process:edit</code></td></tr></tbody></table>

{% hint style="warning" %}
An HTTP Trigger defaults to `ApiPolicy` authentication. A deployed and activated HTTP endpoint returns **401 to external callers until someone configures an API Policy in the Portal**, and no Tool creates API Policies. Expect this rather than treating the 401 as a fault.
{% endhint %}

### Adding steps and logic

One Tool per shape type. Each **adds a shape to the Draft.** None of them affects a running Process.

<table data-search="false"><thead><tr><th>Tool</th><th>What it does</th><th>Scope</th></tr></thead><tbody><tr><td><code>process_add_task</code></td><td>Adds a Task shape, a single Frends Task execution</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_expression</code></td><td>Adds a Code (statement) or Expression shape</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_native_ai</code></td><td>Adds a Native AI shape that calls a language model inline</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_call_activity</code></td><td>Adds a Call Activity that invokes another Process as a step in this flow</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_dmn</code></td><td>Adds a DMN shape that evaluates a decision table</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_shared_state</code></td><td>Adds a Shared State shape that reads or writes the Process-shared key/value store</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_decision</code></td><td>Adds an exclusive Decision gateway whose C# expression selects one of two outgoing branches</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_decision_branch</code></td><td>Adds an outgoing condition branch from a Decision gateway</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_inclusive_gateway</code></td><td>Adds an Inclusive Gateway: independently evaluated conditional branches plus an optional default, so every matching branch runs</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_inclusive_branch</code></td><td>Adds an outgoing branch from an Inclusive Gateway</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_foreach</code></td><td>Adds a sequential Foreach loop scope that iterates the collection its expression produces, exposing each element through the loop variable</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_while</code></td><td>Adds a While loop scope that repeats while its C# expression is true, up to MaxIterations times</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_scope</code></td><td>Adds a Scope container that can hold child shapes</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_return</code></td><td>Adds a Return shape that ends the Process or a scope body and produces its result</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_intermediate_return</code></td><td>Adds an IntermediateReturn shape, which emits a partial response while the Process keeps running, unlike <code>process_add_return</code></td><td><code>process:edit</code></td></tr><tr><td><code>process_add_throw</code></td><td>Adds a Throw shape, which raises an exception at that point in the flow when the Process runs</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_catch</code></td><td>Adds a Catch event that begins an error-handling branch. When an exception is raised in the associated scope, control transfers there and the exception is bound to the variable named by ExceptionVariableName</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_hydration_point</code></td><td>Adds a Hydration Point, which suspends the Process at that step and persists its state, freeing the Agent until it is resumed</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_signal_rehydration</code></td><td>Adds a Signal Rehydration shape, which resumes a stored checkpoint on demand when signalled with a matching correlation id</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_scheduled_rehydration</code></td><td>Adds a Scheduled Rehydration shape, which resumes a suspended Process on a timer rather than waiting for an external event</td><td><code>process:edit</code></td></tr></tbody></table>

{% hint style="info" %}
Adding shapes is not enough on its own. A shape that is never connected does not run, and `validate_process` is what tells you the graph is complete.
{% endhint %}

### Changing a Draft

Tools for editing a Draft in Frends, such as creating flows between shapes or removing shapes.

<table data-search="false"><thead><tr><th>Tool</th><th>What it does</th><th>Scope</th></tr></thead><tbody><tr><td><code>process_edit_shape</code></td><td>Replaces the configuration of a shape already added</td><td><code>process:edit</code></td></tr><tr><td><code>process_batch_mutate</code></td><td>Applies several mutations in one atomic operation, which is the efficient path for many edits</td><td><code>process:edit</code></td></tr><tr><td><code>process_add_connection</code></td><td>Connects two shapes with a sequence flow, defining execution order</td><td><code>process:edit</code></td></tr><tr><td><code>process_remove_connection</code></td><td>Removes the connection between two shapes, identified by the connection's endpoint ids</td><td><code>process:edit</code></td></tr><tr><td><code>process_remove_shape</code></td><td>Removes a shape by its id</td><td><code>process:edit</code></td></tr><tr><td><code>process_set_error_handler</code></td><td>Sets the Process-global error handler: a subprocess invoked when an unhandled exception reaches the top of this Process</td><td><code>process:edit</code></td></tr></tbody></table>

## Deploying and running <a href="#deploying-and-running" id="deploying-and-running"></a>

Both take a `deploymentId` from `list_processes`. These are the two Tools that change what happens in a running Environment, so they are the two scopes to think hardest about before granting.

| Tool             | What it does                                                                                                                                                                                                                          | Scope             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `deploy_process` | Deploys a Process version to a target Agent Group. Its `activateTriggers` parameter defaults to `true`, so omitting it activates the version's triggers after deployment. Pass `activateTriggers: false` to deploy without activating | `process:deploy`  |
| `start_process`  | Triggers execution of a deployed Process                                                                                                                                                                                              | `process:execute` |

## Monitoring <a href="#monitoring" id="monitoring"></a>

`get_process_instance_details` is what a client reads when diagnosing a failure.

| Tool                           | What it does                                                   | Scope                   |
| ------------------------------ | -------------------------------------------------------------- | ----------------------- |
| `get_process_instances`        | Lists execution instances of Processes in a given Agent Group  | `process_instance:view` |
| `get_process_instance_details` | Returns the full execution detail of a single Process Instance | `process_instance:view` |

## Guides <a href="#guides" id="guides"></a>

Retrieved with `list_guides` and `get_guide`.

<table data-search="false"><thead><tr><th>Guide</th><th>Purpose</th></tr></thead><tbody><tr><td><code>find-integration</code></td><td>Locate the Process or integration that handles something</td></tr><tr><td><code>search-processes</code></td><td>Search the Process list by intent</td></tr><tr><td><code>process-authoring</code></td><td>Build a Process correctly, in the expected order</td></tr><tr><td><code>diagnose-process</code></td><td>Investigate a failing Process</td></tr><tr><td><code>execute-process</code></td><td>Run a Process and read the result</td></tr><tr><td><code>explore-tasks</code></td><td>Find and understand the available Tasks</td></tr><tr><td><code>manage-environments</code></td><td>Work with Environments and Environment Variables</td></tr></tbody></table>

### Resources <a href="#resources" id="resources"></a>

The server also serves MCP resources, which a client reads rather than calls.

| Resource                       | Contents                                          |
| ------------------------------ | ------------------------------------------------- |
| `frends://environments`        | The Environments on the Tenant                    |
| `frends://ai-models`           | The AI models available                           |
| `frends://processes/{id}`      | One Process                                       |
| `frends://processes/{id}/link` | A link that opens a Process in the Process Editor |
| `frends://tasks/{name}/schema` | The parameter schema of one Task                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/reference/frends-mcp/frends-mcp-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.