---
title: MCP Tool Trigger in Kestra – Expose Flows as AI Tools
description: Use the McpToolTrigger to expose Kestra flows as tools on an MCP server. AI agents can discover and invoke them automatically, with inputs and outputs mapped to a JSON schema.
url: https://kestra.io/docs/workflow-components/triggers/mcp-tool-trigger
---

# Expose Flows as MCP Tools with the McpToolTrigger

Expose a flow as a named tool on a Kestra MCP server.

The `McpToolTrigger` makes any flow discoverable and callable by MCP-compatible AI agents such as Claude Desktop, Claude Code, and Cursor. Flow inputs are automatically converted to a JSON schema tool spec so the AI agent knows exactly what parameters to pass. Each invocation creates a new flow execution tagged with `system.from:mcp` for observability.

```yaml
type: io.kestra.plugin.core.trigger.McpToolTrigger
```

:::alert{type="info"}
Every tenant has a `default` MCP server provisioned on startup, so the trigger works without creating a server first. See [Flow MCP servers](https://kestra.io/docs/ai-orchestration/mcp-server) to create additional servers and connect AI agent clients.
:::

## Example

```yaml
id: hello_world
namespace: company.team

inputs:
  - id: user
    type: STRING
    defaults: John Doe
    description: "The name of the user to greet."

tasks:
  - id: greet
    type: io.kestra.plugin.core.output.OutputValues
    values:
      greeting: "Hello, {{ inputs.user }}!"

outputs:
  - id: greeting
    type: STRING
    value: "{{ outputs.greet.values.greeting }}"

triggers:
  - id: mcp
    type: io.kestra.plugin.core.trigger.McpToolTrigger
    toolName: hello_world
    title: Hello World greeting tool
    toolDescription: Returns a personalised greeting. Call this when the user asks for a greeting.
    mcpServer: default
```


<div style="position: relative; padding-bottom: calc(49.0084% + 41px); height: 0px; width: 100%;"><iframe src="https://demo.arcade.software/T50B5gunEbBXP5caS8yl?embed&embed_mobile=tab&embed_desktop=inline&show_copy_link=true" title="Flow as an MCP Tool in Kestra" frameborder="0" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write; autoplay" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; color-scheme: light;" ></iframe></div>

## Properties

| Property | Required | Default | Description |
|---|---|---|---|
| `toolName` | Yes | — | Tool identifier shown to the AI agent. Must contain only alphanumeric characters, hyphens, underscores, or dots, and must start and end with an alphanumeric character. Maximum 64 characters. |
| `title` | Yes | — | Human-readable name shown to the AI agent. |
| `toolDescription` | Yes | — | Description of the tool shown to the AI agent, used to decide when to invoke it. Describe when and why to invoke the tool rather than just what it does; this significantly improves tool-selection accuracy. |
| `mcpServer` | No | `"default"` | ID of the MCP server to register this tool on. Must match the `id` of an existing [flow MCP server](https://kestra.io/docs/ai-orchestration/mcp-server). |
| `annotations.readOnly` | No | `false` | Hint that this tool does not modify its environment. |
| `annotations.destructive` | No | `true` | Hint that this tool may perform destructive updates. Only meaningful when `readOnly` is `false`. |
| `annotations.openWorld` | No | `true` | Hint that this tool may interact with entities outside its closed domain. |
| `annotations.idempotent` | No | `false` | Hint that calling the tool repeatedly with the same arguments has no additional effect. Only meaningful when `readOnly` is `false`. |
| `annotations.returnDirect` | No | `false` | When `true`, the AI agent forwards the raw tool output to the user without further interpretation or summarization. |

Annotations are informational hints for MCP clients. They do not affect execution behavior.

A flow can be registered on exactly one MCP server at a time via the `mcpServer` property. Multiple flows can share the same server, each appearing as a separate tool.

## Common trigger properties

`McpToolTrigger` supports all [common trigger properties](https://kestra.io/docs/workflow-components/triggers#trigger-common-properties), including `when` (a Pebble guard evaluated before invoking the flow) and `inputs` (values passed to flow inputs on each invocation).

## Input and output mapping

Flow inputs and outputs are automatically mapped to the MCP tool's input and output schema.

- Each flow `input` becomes a tool parameter. The `description` field on the input is passed to the AI agent as the parameter description.
- Flow `outputs` are returned in the tool response. Each output's `displayName` is used as the label in the response.

To constrain the structure of a `JSON`-type input, use the `jsonSchema` property. See [JSON input validation](https://kestra.io/docs/workflow-components/inputs#input-validation).

## Observability

Every execution created via MCP carries these [system labels](https://kestra.io/docs/concepts/system-labels):

| Label | Value |
|---|---|
| `system.from` | `mcp` |
| `system.mcpServerId` | The `id` of the MCP server that invoked the tool |
| `system.mcpSessionId` | The session ID of the MCP client connection |

Filter executions by `system.from: mcp` in the Executions view to see all MCP-triggered runs.