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.

Managing MCP servers

Navigate to Tenant → MCP Servers in the left sidebar to view, create, edit, and manage 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. The oauthProvider field specifies which provider to use by its configured name:

# 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.

If multiple OIDC providers are configured, set oauthProvider to the name of the specific provider (e.g. my-oidc-provider from the example above). If oauthProvider is omitted, the provider is matched automatically by the JWT’s issuer claim.

Connect an AI agent client

Open a server in the UI and click the Connect tab. It shows the server URL 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 over SSE.
• Claude Code: a claude mcp add command that uses --transport http.
• Cursor: the server URL to paste into Cursor Settings > MCP > Add new MCP server.
• Codex: the connection configuration.

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.

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.

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.