Core Plugins and tasks McpToolTrigger

Core Plugins and tasks McpToolTrigger

Certified

Expose a flow as an MCP tool.

Registers this flow as a named tool on the configured MCP server, making it callable by MCP-compatible AI agents such as Claude Desktop, Claude Code, Cursor, and Codex. The tool's JSON schema is auto-generated from the flow's declared inputs and outputs. Each invocation creates a new flow execution tagged with system.from: mcp for observability.

A flow can be registered on exactly one MCP server at a time (controlled by mcpServer). Multiple flows can share the same MCP server, each appearing as a separate tool in the tool list.

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

Expose a greeting flow as an MCP tool on the default server.

yaml
id: hello_world
namespace: company.team

inputs:
  - id: user
    type: STRING
    defaults: John Doe

tasks:
  - id: hello
    type: io.kestra.plugin.core.output.OutputValues
    values:
      myresult: "hello {{ inputs.user }}"

outputs:
  - id: result
    type: STRING
    value: "{{ outputs.hello.values.myresult }}"

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

Read-only reporting tool registered on a dedicated analytics MCP server.

yaml
id: sales_report
namespace: company.analytics

inputs:
  - id: period
    type: STRING
    description: "Reporting period, e.g. 2025-Q1"

tasks:
  - id: generate_report
    type: io.kestra.plugin.core.log.Log
    message: "Generating report for {{ inputs.period }}"

triggers:
  - id: mcp
    type: io.kestra.plugin.core.trigger.McpToolTrigger
    toolName: sales_report
    title: Sales Report Generator
    toolDescription: Generates a sales report for the given period. Safe to call repeatedly with the same arguments.
    mcpServer: analytics-server
    annotations:
      readOnly: true
      destructive: false
      idempotent: true
Properties

Human-readable display name shown to AI agents in the tool list.

A concise, descriptive title that helps the AI agent understand what this tool does at a glance.

Description of what this tool does and when an AI agent should call it.

Used by AI agents to decide whether to invoke this tool for a given user request. A well-written description significantly improves tool-selection accuracy. Describe what the tool does, when it should be called, and what inputs it expects.

Validation RegExp^[a-zA-Z0-9]([a-zA-Z0-9_.-]*[a-zA-Z0-9])?$
Min length1
Max length64

Unique tool identifier used by AI agents to invoke this tool.

Must contain only alphanumeric characters, hyphens, underscores, or dots, and must start and end with an alphanumeric character. Maximum 64 characters. Choose a short, descriptive name that reflects the flow's purpose (e.g., get_customer_orders or send_slack_notification).

Defaultfalse

Specifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.

Default{ "readOnly": false, "openWorld": true, "destructive": true, "idempotent": false, "returnDirect": false }

Behavioural hints that inform AI agents how to invoke this tool safely.

These annotations follow the MCP tool annotation specification and help AI agents reason about side effects, idempotency, and safety before calling the tool.

Definitions

Tool behaviour hints following the MCP annotation specification.

destructiveboolean

Whether this tool may perform destructive updates.

Only meaningful when readOnly is false. Set to false for tools whose effects can be safely undone or are non-destructive (e.g., creating a record). Default is true.

idempotentboolean

Whether calling this tool repeatedly with the same arguments has the same effect as calling it once.

Only meaningful when readOnly is false. Set to true for tools whose repeated invocation produces no additional side effects beyond the first call.

openWorldboolean

Whether this tool may interact with external entities beyond its closed domain.

Set to true if the tool reaches external systems such as third-party APIs, databases, or file systems outside the Kestra environment.

readOnlyboolean

Whether this tool is read-only.

Set to true if the tool does not modify any state or produce side effects. When true, destructive and idempotent are not meaningful.

returnDirectboolean

Whether the tool result should be returned directly to the user without further AI processing.

When true, the AI agent forwards the raw tool output to the user rather than interpreting or summarising it.

Defaultdefault

ID of the MCP server on which this tool is registered.

Must match the id of an existing MCP server configured in Admin → MCP Servers. Defaults to default, the server that is automatically provisioned for every tenant.

SubTypestring
Possible Values
CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

List of execution states after which a trigger should be stopped (a.k.a. disabled).

Defaulttrue

A condition that determines whether the trigger should run.

A Pebble expression evaluated at trigger time. The trigger fires only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number). Use this to gate trigger execution on dynamic runtime values such as execution labels, flow variables, or environment conditions.

More Plugins in this Category

Ruby
Ruby

Tasks that run Ruby scripts.

Core

4 tasks

Lua
Lua

Tasks that run Lua scripts.

Core

2 tasks