MCP

Manage Kestrel workflows through the Model Context Protocol for AI agent integration

The Kestrel MCP server exposes workflow management as tools that AI coding agents (Cursor, Claude Desktop, OpenAI Codex, etc.) can call directly. This lets you create, modify, and monitor workflows through conversational AI.

Prerequisites

Install the Kestrel CLI:

brew install KestrelAI/tap/kestrel

Authentication is optional up front. The MCP server starts without credentials and exposes only whoami, register, verify_email, login, and create_api_key; as soon as an API key exists (both verify_email and login create one, named after the connected harness) the full tool set is registered and tools/list_changed is emitted. Credentials live in ~/.kestrel/config.json, so kestrel auth kestrel_sk_... works too if you already have a key.

For the end-to-end agent flow with every human step marked, see the Agent Quickstart.

Setup

The MCP server runs as a subcommand of the CLI. Configure your AI tool to run kestrel mcp.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kestrel": {
      "command": "kestrel",
      "args": ["mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kestrel": {
      "command": "kestrel",
      "args": ["mcp"]
    }
  }
}

OpenAI Codex

Add via the Codex CLI:

codex mcp add kestrel -- kestrel mcp

Or add to ~/.codex/config.toml:

[mcp_servers.kestrel]
command = "kestrel"
args = ["mcp"]

If kestrel isn’t on your PATH, use the full path (e.g., /usr/local/bin/kestrel).

Available Tools

Bootstrap and Status

Available before authentication (bootstrap) and after it (status).

Tool	Description
whoami	Server, auth mode (none / session / API key), user, tenant; tells an unauthenticated agent what to call next
register	Create an account; the user then reads a 6-character code from their inbox (human step)
verify_email	Finish registration with the code; logs in, creates an API key, unlocks all tools
login	Existing account with email/password; same key creation. 2FA/SSO accounts are told to create a key in the web app
create_api_key	Create a key (name, scopes, expiry); adopted automatically if the session has none
get_onboarding_status	Checklist (account, keys, connected integrations, workflows, subscription) plus one next recommended step
get_account_status	Plan, trial days left, credit used, daily execution cap, blocked reason, billing URL (card entry is a human step)

Workflow Management

Tool	Description
list_workflows	List all workflows, optionally filtered by status
get_workflow	Get workflow details including definition and trigger config
create_workflow	Create a new workflow from a definition; simulated=true saves it as simulated (testable with mocked outputs, activates once its integrations are connected)
update_workflow	Update a workflow’s name, description, or definition
delete_workflow	Delete a workflow
activate_workflow	Activate a workflow
pause_workflow	Pause an active workflow
duplicate_workflow	Copy a workflow as a new draft

Workflow Generation

Tool	Description
generate_workflow	Generate a workflow from natural language; simulated=true builds as if every integration were connected (prototype before connecting anything)
request_workflow	Submit a request to trigger a matching workflow
list_suggested_workflows	Get AI-suggested workflows

Execution Management

Tool	Description
list_executions	List executions for a workflow
get_execution	Get execution details including step results
cancel_execution	Cancel a running execution
get_workflow_stats	Aggregate execution statistics

Approval Management

Tool	Description
list_pending_approvals	List pending approval gates
approve_step	Approve a gate (with optional justification)
reject_step	Reject a gate

Request Management

Tool	Description
list_unmatched_requests	List unmatched workflow requests
approve_workflow_request	Approve a request
reject_workflow_request	Reject a request

Catalog and Integrations

Tool	Description
get_catalog	Available signal triggers and action blocks
get_integrations_status	Integration connection status

Integration Management

Tool	Description
list_integrations	List every integration with its type, required credential fields, connection status, and how to connect it
connect_integration	Connect any integration. Token/knowledge: immediate. OAuth (GitHub, GitLab, Slack): returns the URL for the human to approve. aws: returns the CloudFormation launch URL, CLI command, and external_id; call again with verify=true and {role_arn, external_id}. gcp: returns the Cloud Shell setup script; call again with verify=true and {project_id}. oci: credentials from the OCI console. kubernetes: returns Helm values and the install command
get_connection_status	Normalized state (connected / pending / summary / details) for any integration
wait_for_connection	Poll until an integration connects after a human or cloud step (default 240s, max 600s; returns pending on timeout)
test_integration	Test a connected integration’s credentials
disconnect_integration	Disconnect a token integration or knowledge source

For credential safety, prefer the CLI’s interactive hidden prompts for secrets (kestrel integrations connect <name>) over pasting tokens into an agent chat when a human is present.

Client identification

Every request the MCP server makes carries X-Kestrel-Client: mcp/<harness>/<version> from the MCP initialize handshake, and the CLI sends cli (or cli/agent/<name> when KESTREL_AGENT is set). Kestrel records this at signup and on every audited action so agent-driven usage is attributable.

Example Conversations

Creating a workflow:

“Create a workflow that triggers when a PagerDuty alert fires, runs K8s RCA, and posts results to #incidents on Slack”

The AI agent calls generate_workflow, reviews the result, then create_workflow and activate_workflow.

Checking executions:

“Show me the last 5 failed workflow executions and what went wrong”

The agent calls list_workflows, list_executions, then get_execution for failed ones.

Approving a gate:

“Are there any pending approvals? Approve the production deployment one”

The agent calls list_pending_approvals, identifies the right one, and calls approve_step.

Connecting an integration:

“Connect our PagerDuty account to Kestrel”

The agent calls list_integrations to find the required credential fields, asks you for the values, then calls connect_integration and verifies with test_integration.