AI CallTool
CertifiedCall a tool on an MCP server and return its result
AI CallTool
Call a tool on an MCP server and return its result
Connects to a Model Context Protocol (MCP) server, invokes one of its tools with the given arguments, and returns the result — no LLM involved. Use io.kestra.plugin.ai.mcp.ListTools to discover the available tools and their argument schemas first.
type: io.kestra.plugin.ai.mcp.CallToolExamples
Call the add tool on an MCP server over Streamable HTTP.
id: mcp_call_tool
namespace: company.ai
tasks:
- id: call
type: io.kestra.plugin.ai.mcp.CallTool
url: https://mcp.example.com/mcp
headers:
Authorization: "Bearer {{ secret('MCP_API_TOKEN') }}"
tool: add
arguments:
a: 5
b: 12
Properties
tool *string
Tool name
Name of the MCP tool to invoke, as reported by the server. No default: this property is required.
url *string
URL of the MCP server
Streamable HTTP or SSE endpoint of the MCP server, matching the chosen transport. No default: this property is required.
arguments object
Tool arguments
Arguments passed to the tool, matching the input schema the server advertises. Not set by default (no argument).
assets
Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.
io.kestra.core.models.assets.AssetsDeclaration
IGNOREFAILWARNAsset failure behavior
Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.
Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.
The assets consumed as inputs.
io.kestra.core.models.assets.AssetIdentifier
1The assets produced as outputs.
io.kestra.plugin.ee.assets.Dataset
1150{}1150io.kestra.plugin.ee.assets.File
1150{}1150io.kestra.plugin.ee.assets.Table
1150{}1150io.kestra.plugin.ee.assets.VM
1150{}1150io.kestra.core.models.assets.External
1150{}1150io.kestra.core.models.assets.Custom
11501Custom asset type
{}1150failOnToolError booleanstring
trueFail on tool error
If true, the task fails when the MCP server reports the tool call as an error. If false, the task succeeds and the failure is surfaced through the isError and errorMessage outputs instead. Defaults to true.
headers object
Custom headers
Extra HTTP headers sent with every request, typically to carry an authentication token via the Authorization header. Not set by default.
logRequests booleanstring
falseLog requests
If true, requests sent to the MCP server are logged at INFO level. Defaults to false.
logResponses booleanstring
falseLog responses
If true, responses received from the MCP server are logged at INFO level. Defaults to false.
timeout string
Connection timeout duration
Maximum time to wait for a response from the MCP server. Not set by default, in which case the underlying MCP client's own default applies and this task enforces no timeout.
transport string
STREAMABLE_HTTPSTREAMABLE_HTTPSSEUNKNOWNTransport
Protocol used to reach the MCP server: STREAMABLE_HTTP or SSE. Defaults to STREAMABLE_HTTP.
Outputs
errorMessage string
Error message
Message describing why the tool call failed. Populated only when failOnToolError is false and the call failed.
isError boolean
Error flag
Whether the MCP server reported the tool call as an error. Only meaningful when failOnToolError is false, since the task fails otherwise.
result string
Tool result
Text result returned by the tool.
structuredContent object
Structured content
Structured payload returned by the tool, present only when the server provided one alongside the text result.
Metrics
mcp.tool.calls counter
callsNumber of MCP tool calls, tagged by tool name
