Configure Kestra MCP Servers and Connect AI Agents

A Kestra MCP server exposes flows as named tools over HTTP for AI agents to discover and call.

A Kestra MCP server is a tenant-scoped entity that uses the Model Context Protocol. Any flow with an McpToolTrigger is automatically 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. For using external MCP servers from within flows, see AI Agents.

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.

Connecting 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 — JSON block to add to claude_desktop_config.json. Claude Desktop does not natively support HTTP MCP servers, so the snippet uses npx mcp-remote as a bridge over SSE.
• Claude Code — claude mcp add command using --transport http. Run it in your terminal, then start Claude Code from the same terminal session so the auth header is in scope.
• Cursor — server URL to paste into Cursor Settings → MCP → Add new MCP server
• Codex — connection configuration

For Basic Auth, the snippet references ${KESTRA_BASIC_AUTH} as a placeholder. Replace it with the actual base64-encoded username:password value inline; the variable reference does not expand at connection time:

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.