Agent Setup

Keel exposes a local, typed MCP server and an equivalent CLI surface for strategy research. This page is for external agents such as Claude Code, Cursor, Windsurf, Codex, and other stdio MCP clients. The Keel web app's managed chat may use internal tool names; do not copy those internal names into MCP instructions. For local agents, the active tools/list response and the keel_* tool schemas are authoritative.

Quick start

pipx install keel-trade
claude mcp add keel -- keel mcp serve

Open your agent and say:

"Connect to Keel."

The agent calls keel_auth_login, your browser opens to app.usekeel.io/oauth/connect, you complete OAuth 2.1 + PKCE consent, and tokens are cached in ~/.keel/config.yaml. The same login covers MCP calls and direct keel CLI usage.

Headless terminal alternative:

keel auth login --key <token>

Create the token at app.usekeel.io/settings?tab=api-keys.

MCP server

Register this command with any stdio MCP client:

keel mcp serve

Claude Code:

claude mcp add keel -- keel mcp serve

Cursor:

{
  "mcpServers": {
    "keel": {
      "command": "keel",
      "args": ["mcp", "serve"]
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "keel": {
      "command": "keel",
      "args": ["mcp", "serve"]
    }
  }
}

Codex:

codex mcp add keel -- keel mcp serve

Local read-only tools such as component search, compose help, status, and knowledge lookup work without auth. API-backed tools such as backtest, accounts, sharing, and live deployment require a login.

The agent host launches keel mcp serve as a child process and talks to it over stdin/stdout. Users do not need to run a daemon, open a port, or start a separate local service. This keeps tool calls connected to the user's local files, project workspace, and cached CLI auth context.

MCP tools

tools/list returns the active set under KEEL_TOOLSETS. The default SDK surface loads always,read-only,backtest,share,live-read, which exposes the normal research workflow plus read-only live monitoring and omits live-trading mutation tools.

For exact tool schemas, required args, safety annotations, and CLI equivalents, use the generated MCP Tool Reference.

For components, use keel_components_search to find candidates, keel_components_detail_batch to compare several schemas before composing, and keel_components_compose_help only for one known component's schema/detail.

To expose live write tools to MCP clients, start the server with:

KEEL_TOOLSETS=always,read-only,backtest,share,live-read,live-write keel mcp serve

Actual live deployment still requires all safety gates:

• OAuth live scope: keel auth login --scope live
• Local machine arming: keel arm live set --account <account_id>
• Explicit deploy intent: keel_live_deploy(preview=False, ...) or keel live deploy <strategy_id> --account-id <account_id> --no-preview

Always preview first with keel_live_deploy(preview=True, ...).

MCP resources

Agents can also read these resources:

Workflow prompts

Good prompts map to specific Keel tool calls:

1. "Connect to Keel and show my status." The agent calls keel_auth_login, then keel_status.

2. "Find momentum and funding components that can be composed together." The agent calls keel_components_search and keel_components_detail_batch.

3. "Compose a funding-carry strategy, validate it, and save it as my baseline." The agent calls keel_strategy_compose first with dry_run=True, then again with dry_run=False when the source is valid.

4. "Backtest my baseline from 2025-06-01 through 2026-02-01 and summarize it." The agent calls keel_backtest_run; if the run is still active, it calls keel_backtest_watch(backtest_id=<run_id>); if it needs more terminal detail, it calls keel_backtest_summarize(backtest_id=<run_id>).

5. "Preview a live deployment for this strategy on account acct_123." The agent calls keel_live_deploy(preview=True, ...). It should not call preview=False unless the user explicitly asks to deploy live.

Bundled skills

Keel ships behavioral skills for agent hosts that support them:

When a skill mentions tools, use the current keel_* MCP schemas from tools/list for exact argument names. Some bundled research knowledge is also used by Keel's web chat; if a shared note names an internal chat tool, prefer the MCP tool listed in the skill frontmatter.

CLI for shell-based agents

Agents can also call the CLI. In agent contexts the CLI auto-selects JSON where possible, and every outcome command has an underscore-equivalent MCP tool:

keel status --format json
keel components search momentum --format json
keel components describe-batch ROC FundingRate --format json
keel strategy compose --source-file strategy.py --dry-run --format json
keel strategy compose --source-file strategy.py --name carry-baseline --format json
keel backtest run str_abc123 --start-date 2025-06-01 --format json
keel backtest watch btr_xyz789 --format json

--end-date is optional for keel backtest run and defaults to today's UTC date. Pass it when you need a fixed historical window.

For a project-level agent instruction file, keep it small and current:

## Keel Strategy Development

Use Keel for strategy research.

1. Check status: `keel status --format json`
2. Search components: `keel components search momentum --format json`
3. Inspect schemas: `keel components describe-batch ROC FundingRate --format json`
4. Validate source: `keel strategy compose --source-file strategy.py --dry-run --format json`
5. Save source: `keel strategy compose --source-file strategy.py --name <name> --format json`
6. Backtest: `keel backtest run <strategy_id> --start-date YYYY-MM-DD [--end-date YYYY-MM-DD] --format json`
7. Watch if needed: `keel backtest watch <backtest_id> --format json`

If a command is not shown by `keel --help`, do not call it. For current
workflows, prefer compose, watch, summarize, monitor, and control commands shown
above.

Auth and safety

Use keel_status or keel status first when an agent session starts. If a remote tool returns an auth error, call keel_auth_login or run keel auth login.

Live trading is deliberately harder than research:

• KEEL_TOOLSETS only controls MCP exposure; the CLI always has the command group available.
• keel live deploy defaults to preview mode.
• Actual deployment requires --no-preview, OAuth live scope, and local arming.
• Control actions use one tool: keel_live_control(deployment_id=<id>, action="pause"|"resume"|"stop"|"trigger").
• keel_live_monitor returns freshness metadata. Positions are on-demand Hyperliquid snapshots; portfolio/history views are backend records and can lag the web dashboard live stream.

Troubleshooting

keel doctor
keel auth status
keel status --format json
keel components search <partial_name> --format json
keel help dsl_syntax

Common recovery paths:

• Not authenticated: call keel_auth_login or run keel auth login.
• Missing live write tools in MCP: restart with KEEL_TOOLSETS=always,read-only,backtest,share,live-read,live-write.
• Live deploy rejected: verify keel auth login --scope live, then keel arm live set --account <account_id>.
• Strategy source rejected: rerun keel_strategy_compose or keel strategy compose in dry-run mode and follow the structured error.