MCP API reference

Every tool exposed by the Bagtester MCP server. JSON-RPC over HTTP POST.

Endpoint

http

POST https://bagtester.com/api/mcp
Authorization: Bearer bag_yourkeyhere
Content-Type: application/json

Tools

submit_strategyrequired

Submit a Python strategy for backtesting. Returns standardized metrics.

Param	Type	Description
code	string (required)	Python source. Subclass bagtester.Strategy.
mode	minute \| hybrid \| tick (default: minute)	Execution mode.
symbol	string (required)	BTCUSDT, EURUSD, AAPL, SPY, etc.
from_date	YYYY-MM-DD	Backtest start.
to_date	YYYY-MM-DD	Backtest end.
initial_capital	number (default: 10000)	Starting capital.
params	object (optional)	Forwarded to your Strategy.__init__(**params).
fee_profile	auto \| crypto_spot \| fx_major \| us_stock \| us_etf	Per-asset cost preset.
commission_bps	number (optional)	Override commission.
slippage_bps	number (optional)	Override slippage.
wait	boolean (default: true)	true = sync; false = returns job_id only.
timeout_seconds	integer (default: 300)	Max time to wait for sync result.

get_backtest_resultsrequired

Retrieve a previously submitted backtest by job_id.

Param	Type	Description
job_id	string (required)	From a previous submit_strategy call.
timeout_seconds	integer (default: 60)	Max wait if still running.

list_my_jobsrequired

List your most recent backtest jobs (id, status, mode, symbol, dates, credits).

Param	Type	Description
limit	integer (default: 20, max 100)	Number of jobs to return.

list_available_datanot required

Asset universe + timeframes + tier-access metadata. Use this to discover what's submittable.

get_data_samplenot required

Last N OHLCV bars for a symbol — verify schema and value ranges before submitting.

Param	Type	Description
symbol	string (required)	BTCUSDT, EURUSD, etc.
timeframe	1m \| 5m \| 15m \| 1h \| 4h \| 1d (default: 1m)	Bar size.
n	integer (default: 10, max 200)	Number of rows.
asset_class	crypto \| fx \| stocks \| etfs (default: crypto)	Used to route data lookup.

optimize_strategyrequired (Quant)

Run a parameter sweep. Returns ranked top combinations by primary_metric.

Param	Type	Description
code, mode, symbol, from_date, to_date, initial_capital	—	Same as submit_strategy.
param_grid	object (required)	{ paramName: [v1, v2, ...] } — Cartesian product.
primary_metric	sharpe_ratio \| sortino_ratio \| total_return_pct \| cagr_pct	Ranking metric.
max_combinations	integer (default: 200, max 500)	Hard cap on combinations.
timeout_seconds	integer (default: 900)	Sync timeout.

walk_forwardrequired (Quant)

Rolling in/out-of-sample test. Detects overfit by comparing OOS to in-sample.

Param	Type	Description
code, mode, symbol, from_date, to_date, initial_capital	—	Same as submit_strategy.
param_grid	object (required)	Optimized within each in-sample window.
in_sample_days	integer (default: 90)	Length of optimization window.
out_sample_days	integer (default: 30)	Length of evaluation window.
primary_metric	sharpe_ratio \| sortino_ratio \| total_return_pct \| cagr_pct	Optimization metric.
max_combinations	integer (default: 50, max 200)	Per-window cap.

improve_strategyrequired

Re-run a previous job with a structured improvement (extend range, switch to hybrid/tick, parameter sweep).

Param	Type	Description
job_id	string (required)	ID of a previous job.
improvement_id	extend_time_range \| use_hybrid_mode \| use_tick_mode \| parameter_sweep	Which improvement to apply.
param_grid	object	Required for parameter_sweep.
from_date / to_date	YYYY-MM-DD	Override for extend_time_range.

Response shapes

All responses include schema_version. Successful single backtests return:

json

{
  "job_id": "bt_3a7f...",
  "status": "completed",
  "mode": "minute",
  "summary": {
    "total_return_pct": 24.7,
    "cagr_pct": 26.1,
    "sharpe_ratio": 1.83,
    "sortino_ratio": 2.41,
    "max_drawdown_pct": -14.2,
    "win_rate": 0.58,
    "trades_total": 87,
    "credits_used": 1
  },
  "equity_curve": [{ "timestamp": "2024-01-01T00:00:00", "equity": 10000.0 }, ...],
  "trades": [...],
  "billing": {
    "charged": 1,
    "remaining_credits": 99,
    "capped": false
  }
}

Errors

JSON-RPC 2.0 error codes:

-32700 — Parse error.
-32601 — Method or tool not found.
-32603 — Internal error (with details).
-32001 — Authentication required (no Bearer token).