# Write to MCP tool

Invoke an integration's MCP tool once per record.

## When to use it

Call a connected service tool once per input record. Read the tool’s actual effect: it can write or act externally. Duplicate prevention depends on the service honouring the supplied key; inspect uncertain outcomes before repeating calls.

## Add and configure

1. Add **Write to MCP tool** from the workflow step picker.
2. Give the step a recognisable name and connect its required inputs.
3. Set the options below. Nested names identify fields within an object or a list item.
4. Validate the recipe, inspect the test result, then run it on the intended data.

The step identifier used in the editor’s code view is `write_to_mcp`.

## Settings

| Setting | Accepted value | Required | Default | What it controls |
| --- | --- | --- | --- | --- |
| Concurrency (`concurrency`) | integer; minimum 1; maximum 32 | No | 4 | Max in-flight MCP calls per step execution. Set to 1 for strict serial ordering (matches prior behavior). |
| Idempotency Key Template (`idempotency_key_template`) | string or null | No | null | When set, each tool call carries an `Idempotency-Key` header rendered from this template (variables: `${tenant_id}`, `${run_id}`, `${step_id}`, `${record_seq}`). The MCP gateway is expected to honor the header for idempotent dispatch; absent gateway support the key is logged and still emitted so audit trails align. |
| Integration Id (`integration_id`) | string; format uuid | Yes | Not specified | MCP integration UUID. |
| Payload Path (`payload_path`) | string or null | No | null | Optional JSONPath — when set, the tool is called with the value at this path instead of the whole record. |
| Tool Name (`tool_name`) | string | Yes | Not specified | Name of the tool to invoke. |

## Inputs and outputs

| Direction | Port | Content | Required | Multiple records |
| --- | --- | --- | --- | --- |
| Inputs | `in` | records | Yes | Yes |
| Outputs | `out` | records | Yes | Yes |

## Effects, testing, and recovery

Can write or act on an external destination.

The declared preview behaviour is to skip this step. Configuration can affect preview behaviour; HTTP GET is a notable exception. Read [dry runs](/docs/workflows/dry-runs) before using a preview with live connections.

Duplicate prevention uses the configured or operation-bound key; an external receiver must recognise it. Do not assume that manually repeating the step is free of repeated effects.

## Example: Post each record's message through a chat integration

Step settings:

```json
{
  "idempotency_key_template": "${run_id}:${record_seq}",
  "integration_id": "88888888-8888-4888-8888-888888888888",
  "payload_path": "$.message",
  "tool_name": "send_message"
}
```

## Example: Serial calls with the whole record as the tool arguments

Step settings:

```json
{
  "concurrency": 1,
  "integration_id": "88888888-8888-4888-8888-888888888888",
  "tool_name": "create_ticket"
}
```

## Check the result

Inspect the selected run’s status, counts, errors, and output records. An empty collection can be a valid result, and a completed step can contain per-record failures where the step defines that behaviour. Check the next step’s expected record shape before publishing or delivering the result.