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": {"kind": "compare", "right": [25, 30, 35]}}
  ]}
})

Only value fields can be swept (not left/op/structure). Address leaves inside an all_of/any_of/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.

collect_diagnosticsbooleanCapture per-bar condition diagnostics so explain_bar and get_condition_timeline can explain this run bar by bar. Defaults to false: on a realistic multi-condition strategy capture costs 40-70% more CPU and ~5x the memory, and most runs are never inspected. Leave it off while sweeping or screening; turn it on for the one run you intend to investigate, or recover afterwards with rerun_backtest. Refused on runs above the diagnostics size ceiling -- narrow the date range or use a coarser resolution instead.

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/exit_card_name/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).

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, and allocation (universe/basket runs only). 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%). Equity runs ALSO pay a per-symbol typical half-spread (0.5-2bp) on top of this; it is only waived when fee_pct and slippage_pct are BOTH set to 0, so setting slippage alone to 0 is not a frictionless run.

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

storage_profilestringStorage profile: 'backtest_diagnostic' (default, retains indicators, condition data and bar events) or 'backtest_minimal' (retains none of them). This is RETENTION only -- it cannot persist condition data that was never captured, so explain_bar also needs collect_diagnostics=true.

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

sweepanyOf (2 variants)Run MANY variants in ONE call instead of one backtest per call. Variants execute in parallel and the call waits longer for them, so N variants cost one round trip rather than N. Reach for this whenever you are about to compare more than one version of a strategy. Sweep the CONDITION that the idea turns on: {"mode":"cartesian","overrides":{"conditions":[{"label":"entry.rsi_lt_30","patch":{"kind":"compare","right":[25,30,35]}}]}} — labels are `role.<definition_name>`; call get_strategy_patch_schemas(strategy_id) first to see the labels and patch shapes this strategy accepts. Execution knobs sweep the same way, when THEY are the question: {"mode":"zip_by_index","max_combinations":20,"initial_cash":[50000,100000],"fee_pct":[0.0,0.05]}

wait_for_completionbooleanWait for inline results. Set false to return a queued run handle promptly; poll get_backtest or rediscover with list_runs.