Expose Your Flows as Tools for External AI Agents

Expose your Kestra flows as named tools that external AI agents discover and call over MCP.

This page is for Kestra administrators and flow authors who want Claude, Cursor, or another AI agent to run their flows. If you want your coding agent to look up Kestra plugin schemas and docs while you write flows, use the Docs MCP server instead.

A flow MCP server is a tenant-scoped entity that uses the Model Context Protocol. Any flow with an McpToolTrigger is registered as a named tool on its target server. AI agents discover the tool list at connection time, so adding or removing triggers takes effect without restarting clients.

Two directions: Kestra as server vs. Kestra as client

Kestra supports MCP in both directions:

This page covers Kestra as an MCP server. To call external MCP servers from a flow, see MCP clients.

Default server

A default MCP server is automatically provisioned for every tenant on startup. You can use it immediately with no setup needed. The McpToolTrigger’s mcpServer property defaults to "default", so a minimal trigger requires no explicit server reference. The default server cannot be deleted, and you cannot create another server with the ID default.

Managing MCP servers

Navigate to Tenant → MCP Servers in the left sidebar to view, create, edit, and manage MCP servers.

To script the same tasks, install kestractl and use its mcp-servers commands, or call the REST API at /api/v1/{tenant}/mcp-servers.

Each server has the following fields:

Authentication types

Keep servers private unless you have a specific reason to expose them publicly. A public server allows any MCP client to call any flow registered on it without authentication.

Configuring OAuth authentication

OAUTH auth requires an OIDC provider configured in your Kestra instance (the same configuration used for SSO). See SSO configuration for how to set up an OIDC provider under micronaut.security.oauth2.clients.

Once a provider is configured, set authType to OAUTH on the MCP server and set oauthProvider to the provider’s configured name, my-oidc-provider in the following example. Kestra rejects a name that doesn’t match a configured provider.

# kestra.yml
micronaut:
  security:
    oauth2:
      clients:
        my-oidc-provider:
          client-id: <client-id>
          client-secret: <client-secret>
          openid:
            issuer: https://accounts.example.com

When a client connects to an OAUTH-protected MCP server and presents no token, the server responds with a WWW-Authenticate header pointing to the OAuth Protected Resource Metadata endpoint (RFC 9728). MCP-compliant clients such as Claude web discover the OIDC provider from this automatically and initiate the authorization code + PKCE flow; no manual client configuration is needed beyond the MCP server URL.

Kestra accepts a token only if its issuer matches the provider named in oauthProvider. Also set oauthScopesSupported to the scopes MCP clients should request, for example openid, profile, and email. Kestra advertises them in the Protected Resource Metadata document.

Connect an AI agent client

Open a server in the UI and click the Connect tab. It shows the server URL, <kestra-url>/api/v1/<tenant>/mcp/<server-id>, and ready-to-paste configuration snippets for each supported client:

• Claude Desktop: a JSON block to add to claude_desktop_config.json. Claude Desktop does not support HTTP MCP servers natively, so the snippet uses npx mcp-remote as a bridge.
• Claude Code: a claude mcp add command that uses --transport http.
• Cursor: a JSON block to add to ~/.cursor/mcp.json.
• Codex (OpenAI): a TOML block to add to ~/.codex/config.toml.

For Basic Auth, the snippets contain a ${KESTRA_BASIC_AUTH} placeholder. MCP clients store this text literally and do not expand it when they connect, so replace it with the base64-encoded username:password value. In Claude Code, let your shell compute the value when you add the server:

claude mcp add <server-id> <server-url> \
  --transport http \
  --header "Authorization: Basic $(echo -n 'username:password' | base64)"

Viewing registered tools

The Tool Flows tab on each server lists all flows that have an McpToolTrigger pointing at that server. Use this to audit which flows are exposed and to navigate directly to a flow’s trigger configuration.

To list the same tools from the command line, run kestractl mcp-servers tools <server-id>.

RBAC (Enterprise)

In the Enterprise Edition, MCP_SERVER is a first-class RBAC resource. See RBAC for the default role assignments.

Access to a private server is also flow-scoped: a user can connect to a private MCP server only if they have FLOW: EXECUTE permission on at least one namespace that has a flow with an McpToolTrigger pointing at that server. If no flow points at the server yet, any authenticated user can connect.

MCP server cache configuration

By default, each webserver node caches MCP server configuration in memory and hot-reloads it when a server is created, updated, or deleted. Two optional properties control the cache behavior:

Example configuration:

kestra:
  mcp:
    server-cache-config:
      maximum-size: 200
      expire-after-access: PT10M

Adjust these only if you have a large number of MCP servers or tight memory constraints. The defaults are sufficient for most deployments.