> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usekestrel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.usekestrel.ai/workflows/cli.md):

```bash theme={null}
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](https://docs.usekestrel.ai/workflows/agent-quickstart.md).

## 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`:

```json theme={null}
{
  "mcpServers": {
    "kestrel": {
      "command": "kestrel",
      "args": ["mcp"]
    }
  }
}
```

### Claude Desktop

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

```json theme={null}
{
  "mcpServers": {
    "kestrel": {
      "command": "kestrel",
      "args": ["mcp"]
    }
  }
}
```

### OpenAI Codex

Add via the Codex CLI:

```bash theme={null}
codex mcp add kestrel -- kestrel mcp
```

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

```toml theme={null}
[mcp_servers.kestrel]
command = "kestrel"
args = ["mcp"]
```

> [!TIP]
>
> 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 |

> [!NOTE]
>
> 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.