Agent Setup

How to give AI agents access to Keel — via MCP server, CLI, or both.

Quick Start

pipx install keel-trade
keel auth login                   # Store API key (optional — local tools work without it)

Local tools (component search, strategy validation) work immediately without an API key. Remote tools (backtest, live trading) require auth.

MCP Server (Recommended for IDE Agents)

The MCP server exposes all Keel tools via the Model Context Protocol. Agents discover tools progressively — tools/list returns only 4 lightweight meta-tools (~3K tokens), then the agent calls describe_tool to get full schemas on demand.

Claude Code

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

That's it. Claude Code starts the server automatically. Test with: "Search for momentum components"

If you need remote tools (backtest, live), authenticate first:

keel auth login    # Stores key in ~/.keel/config.yaml — the MCP server reads it automatically

Manual config alternative

Add to ~/.claude/mcp_servers.json:

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

Cursor

Add to .cursor/mcp.json in your project root:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

OpenAI Codex

Add to your codex CLI config or pass at startup:

codex --mcp-config '{"keel": {"command": "keel", "args": ["mcp", "serve"]}}'

Other MCP Clients

Any MCP client that supports stdio transport works. The server command is:

keel mcp serve    # stdio (default)

MCP Tools

The server provides 4 meta-tools:

Tool	Purpose
`search_tools(query)`	Discover available Keel tools by keyword
`describe_tool(name)`	Get full input schema for a tool
`keel_status()`	Check auth, org, plan, entitlements
`execute(tool_name, arguments)`	Run any Keel tool with JSON arguments

Typical agent workflow:

Call keel_status() to check what's available
Call search_tools("validate") to find relevant tools
Call describe_tool("strategy_validate") to get the schema
Call execute("strategy_validate", '{"source": "..."}') to run it

MCP Resources

Read-only context the agent can access:

URI	Content
`keel://components/catalog`	Full component registry
`keel://dsl/reference/{topic}`	DSL reference docs (phases, types, slots, etc.)

CLI (For Tool-Use Agents)

Agents like Claude Code can call the CLI directly as a shell tool. The CLI auto-detects agent mode and outputs JSON.

Agent Mode Detection

The CLI detects agent context automatically via:

Variable	Agent
`CLAUDE_CODE`	Claude Code
`CURSOR_AGENT`	Cursor
`AIDER`	Aider
`GITHUB_COPILOT`	GitHub Copilot
`OPENCLAW_SESSION`	OpenClaw
`KEEL_AGENT_MODE`	Explicit override

When detected (or when stdout is not a TTY):

Output defaults to JSON
No interactive prompts
Structured error messages with suggestions

Override with KEEL_AGENT_MODE=false to force human mode, or --format table for specific commands.

Example: Claude Code CLAUDE.md

Add to your project's CLAUDE.md:

## Keel Strategy Development

This project uses Keel for strategy development. The `keel` CLI is available.

### Workflow
1. Search components: `keel components search --keyword "momentum"`
2. Create strategy: `keel strategy new my_strat --template basic`
3. Validate: `keel strategy validate strategy.py`
4. Check readiness: `keel strategy stage strategy.py`
5. Backtest: `keel backtest run str_xxx --start-date 2025-01-01 --end-date 2025-12-31`

### Key Commands
- `keel components detail <name>` — Full component spec
- `keel strategy patterns "<goal>"` — Composition guidance
- `keel strategy explain <file>` — Pipeline walkthrough
- `keel components reference <topic>` — DSL docs

Skills (Behavioral Instructions)

Skills are bundled workflow guides that teach agents how to use Keel effectively. They include domain knowledge, common mistakes to avoid, and step-by-step procedures.

Available Skills

Skill	Triggers	What it teaches
`strategy-creation`	"create strategy", "new strategy"	Thesis → components → composition → validation
`strategy-backtest`	"backtest", "test strategy"	Pre-check → submit → interpret → iterate
`live-trading`	"deploy", "go live"	Pre-deploy → deploy → monitor → emergency
`portfolio-analysis`	"portfolio", "P&L"	Metrics → cross-deployment → risk
`universe-selection`	"universe", "which coins"	Mode → criteria → resolve → verify
`component-discovery`	"components", "signals"	Search → compatibility → compose

Authentication

API Keys

Get your API key from Settings → API Keys in the dashboard.

# Environment variable (recommended for agents and CI)
export KEEL_API_KEY=sk_org_xxx

# Config file (interactive use)
keel auth login
# Stored in ~/.keel/config.yaml

# Verify
keel auth whoami
keel auth status    # Shows entitlements and active deployments

Precedence: KEEL_API_KEY env var > ~/.keel/config.yaml

What Needs Auth

Domain	Auth Required?
Components (search, detail, list)	No
Strategy (validate, compile, explain, stage, diff)	No
Strategy (create, list, show on platform)	Yes
Universe (get, set, groups — local)	No
Universe (resolve, categories — remote)	Yes
Backtest	Yes
Live trading	Yes
Market data	Yes

Building Custom Agents

Python SDK

The CLI is built on importable Python modules:

from keel.tools.local import (
    strategy_components_search,
    strategy_validate,
    pipeline_stage,
)

# Search components
results = strategy_components_search(keyword="momentum")

# Validate a strategy
result = strategy_validate(source="Pipeline([...], name='test')")

# Check pipeline completeness
stage = pipeline_stage(source=source)
if stage["backtest_ready"]:
    print("Ready to backtest!")

API Client

from keel.client import KeelClient

with KeelClient() as client:
    # List strategies
    strategies = client.get("/v1/strategies")

    # Start backtest
    backtest = client.post("/v1/backtests", json={
        "strategy_id": "str_abc123",
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
    })

    # Check results
    results = client.get(f"/v1/backtests/{backtest['backtest_id']}/results")

Troubleshooting

"Not authenticated"

export KEEL_API_KEY=sk_org_xxx
# or
keel auth login

"Component not found"

# Check exact name (case-sensitive)
keel components search --keyword <partial_name>
keel components list

"Validation failed"

# Get detailed errors
keel strategy validate strategy.py --format json

# Check pipeline completeness
keel strategy stage strategy.py

MCP server not connecting

# Test manually
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}' | keel mcp serve

# Check keel is in PATH
which keel
keel --version

Agent Setup

On this page