run_backtest MCP Tool

Back to MCP catalog

run_backtest

Run a backtest for a strategy over a recent lookback period.

Area

Backtesting & Validation

Group

Backtests

Access

Write

Risk

May change server state

Details

Full description

Run a backtest for a strategy over a recent time period. Uses a lookback from today (e.g. lookback="3mo" = last 3 months), so data is always available.

The run is queued and the call waits up to ~60s for completion. If it's still running when the wait expires you get a backtest_id back — poll get_backtest(backtest_id) until status="completed".

Results — trades are at results.trades. detail="summary" (default) caps at 20 trades; detail="full" caps at 500. results.trade_count is the full count; page the rest with get_backtest(backtest_id, include=["trades"], ...).

Single run

run_backtest(strategy_id, lookback="3mo")   # → backtest_id
get_backtest(backtest_id)                    # poll until completed
compare_backtests([id_a, id_b])              # compare runs

Parameter sweep — vary condition values across many runs in one call. Discover valid labels first with get_strategy_patch_schemas(strategy_id).

run_backtest(strategy_id, sweep={
  "mode": "cartesian",
  "overrides": {"conditions": [
    {"label": "entry.rsi_lt_30", "patch": {"type": "compare", "rhs": [25, 30, 35]}}
  ]}
})

Only value fields can be swept (not lhs/op/structure). Address leaves inside an allOf/anyOf/sequence with the full path role.<composite>.<leaf>.

Capabilities

Bounded options and operating modes surfaced above the full JSON schema.

Detail options

detail

summaryfull

Required Inputs

None.

Optional Inputs

FieldTypeDescription

benchmark_symbolanyOf (2 variants)Optional secondary market-index benchmark symbol (e.g. 'SPY' for a US equities strategy). When set, results include market_benchmark_return and market_benchmark_max_drawdown alongside the per-symbol buy-and-hold benchmark — useful for judging strategy alpha vs. the broad market, not just vs. buy-and-hold of the traded asset.

detailenum: summary, fullResult detail: 'summary' (default, trades capped at 20, per-trade fields slimmed to id/symbol/direction/entry+exit time+price+bar/pnl/exit_reason/is_win/is_open, bar_times dropped, equity_curve returned as parallel arrays) or 'full' (trades capped at 500, full diagnostic shape). Statistics, trade_summary, signal_summary, and equity_summary are unchanged. For the dropped per-trade fields use get_backtest(detail='full'); for paginated access to all trades use get_backtest(include=["trades"], trades_offset, trades_limit); for full per-bar series use get_backtest(include=["ohlc"]).

end_dateanyOf (2 variants)End date (YYYY-MM-DD). Mutually exclusive with lookback.

fee_pctanyOf (2 variants)Trading fee as percentage (0.1 = 0.1%). None=auto-detect (equities=0.00%; crypto/mixed=0.50%). Set 0 for zero fees.

initial_cashnumberInitial cash amount

lookbackanyOf (2 variants)Lookback period from today: '3mo' (3 months), '6mo', '1yr' (year), '2wk' (weeks), '30d' (days). Default: 3mo. Mutually exclusive with start_date/end_date.

overridesanyOf (2 variants)Optional per-run strategy override patch. Overridable sections: sizing, position_policy, execution, risk_policy, conditions. Example: {"sizing":{"mode":"fixed_usd","fixed_usd":5000},"execution":{"order_type":"market"}}. NOTE the key-name difference: builder_set_strategy_config takes patch={'risk': ...}, but here the section is named 'risk_policy' (same name builder_get_strategy reads it back under as config.risk_policy) — 'risk' is rejected as an extra input. To disable the short-equity liquidation floor for one research run: {"risk_policy":{"short_equity_floor_pct":null}}

portfolio_idanyOf (2 variants)Run a portfolio backtest (exercises member rotation / allocation). Mutually exclusive with strategy_id. Portfolio backtests do not support overrides or sweep.

slippage_pctanyOf (2 variants)Slippage as percentage (0.05 = 0.05%). None=auto-detect (equities=0.01%; crypto/mixed=0.05%). Set 0 for zero slippage.

start_dateanyOf (2 variants)Start date (YYYY-MM-DD). Mutually exclusive with lookback.

storage_profilestringStorage profile: 'backtest_diagnostic' (default, enables explain_bar) or 'backtest_minimal' (no indicators, condition data, or bar events)

strategy_idanyOf (2 variants)Strategy identifier. Mutually exclusive with portfolio_id.

sweepanyOf (2 variants)Optional sweep config for multi-run generation. Example: {"mode":"zip_by_index","max_combinations":20,"initial_cash":[50000,100000],"fee_pct":[0.0,0.05]}