MCP tools reference

This is the developer reference for every tool the Forven MCP server exposes. To connect a client first, read MCP server; this page assumes the server is running and your client can see it.

The server surfaces the AI Drop Zone as 21 tools: eleven that only read and ten that write. Each one is a thin HTTP client over the running backend (FORVEN_API_URL, default http://127.0.0.1:8003), so every call does exactly what the matching UI action or REST endpoint does, and the same promotion gates apply.

How to read this reference

• Tool name — the exact string your client calls (all prefixed forven_).
• Key params — the parameters that matter; optional ones are marked.
• Returns — what you get back.
• Backed by — the REST endpoint it calls.

Strategy stages are quick_screen → gauntlet → paper → live_graduated; the graveyard holds archived, rejected and backtest_failed.

Sessions are automatic. The first write call (register or backtest) opens a Drop Zone session, later calls are tagged to it, and it closes when the client disconnects. Write tools accept an optional session_id to resume a specific session.

Read-only tools

forven_get_context

Step 1 — orient. Returns one section of the Drop Zone context.

• Key params: section — overview (default: workspace paths, the workflow and the gotchas), template (fetch before writing a strategy file), datasets, params (canonical parameter families), endpoints (the raw HTTP surface), or all (large).
• Returns: the section, the list of sections, and a next hint.
• Backed by: GET /api/ai-dropzone/context

forven_get_quant_skills

Step 2 — priors. Curated insights from past survivors and failures — for avoiding known dead ends, not guaranteed edges. See quant skills.

• Key params: optional regime (trending, range_bound or volatile), skill_type, min_confidence (default 0.5), limit (default 10).
• Backed by: GET /api/quant-skills

forven_get_data_readiness

Check the data before writing a strategy that reads anything beyond candles — funding, open interest, basis, implied volatility, long/short ratio, taker flow, liquidations.

• Key params: either strategy_id (a registered strategy), or symbol + timeframe for an idea, with optional streams (for example ["funding", "oi"]), history_days and strategy_type.
• Returns: a verdict — ready, needs_data or blocked — a one-sentence summary, and one row per requirement (candles, history depth for the research window plus warm-up, freshness, each feed) with a fix. blocked can't be fixed by downloading — for example liquidation history from before its capture began — so pick another input rather than build a strategy that can never trade.
• Backed by: GET /api/data/readiness/strategy/<strategy_id>, or POST /api/data/readiness

forven_list_strategies

Registered strategies, optionally filtered by status.

• Backed by: GET /api/strategies

forven_get_recent_runs

The last N backtest runs across all strategies (limit, default 20).

• Backed by: GET /api/backtesting/runs

forven_get_result

One backtest result by result_id — full metrics, trades and config. Use it when the compact payload isn't enough.

• Backed by: GET /api/results/<result_id>

forven_get_robustness_result

Step 7b — poll a persisted robustness run submitted by forven_run_robustness. Returns its status (running, succeeded or failed) and, once done, the verdict scorecard. Poll every 15–30 seconds; walk-forward and parameter jitter can take a few minutes.

• Key params: result_id.
• Backed by: GET /api/robustness/results/<result_id>

forven_get_gate_report

Step 8 — the single status readout. A dry run of the real gate to the strategy's next stage. Read-only.

• Key params: strategy_id.
• Returns:
  • strategy and latest_result (its latest backtest, compacted);
  • target_stage — paper for a gauntlet strategy, live_graduated for one already in paper;
  • promotion_ready;
  • failed_gates — each with id, message, severity, an actionable hint and a reason_code — and latest_gate_failure;
  • next_actions, for example run forven_run_robustness when validation evidence is missing.
• Backed by: GET /api/strategies/<id>/container, GET /api/results, and GET /api/lifecycle/strategies/<id>/readiness (or /paper-live-readiness for a paper strategy)

What the two hops mean with the default settings:

• Gauntlet → paper is the door into paper. The default research door admits a strategy that isn't broken or clearly losing: 20+ confirmation trades, a non-negative return, an out-of-sample profit factor of at least 1 and a positive out-of-sample Sharpe, the drawdown and tail-risk floors, and no loss under 2× costs. Every robustness test must have a saved verdict, but the deflated Sharpe, walk-forward fold rate, regime split, jitter and robustness score are only recorded here. The held-back test doesn't run at this hop. If the paper pool is full, a strategy that passes the door waits for a slot.
• Paper → live is where those recorded checks are enforced, together with the sequential forward-evidence test, the breadth test and the one-shot held-back test.

Under Strict paper (Settings → Lab → Door into paper) every check, and the held-back test, blocks the paper hop as before. The tool returns failed_gates only; the raw readiness endpoint behind it also reports the door in force and the pool (paper_door, paper_pool), or for a paper strategy the live-gate settings and sequential-test state (live_gate, live_evidence). python -m forven.agent gate-report returns that readiness payload as it is.

Reason codes worth knowing:

When a paper strategy passes every paper → live gate, the report says so — and that going live needs the operator's typed GO LIVE in the app. Don't try to promote it yourself.

forven_get_paper_readiness

The gate report, labelled for the paper target. Doesn't promote; use forven_start_paper_session for that.

• Key params: strategy_id.

forven_list_sessions

Recent Drop Zone sessions with strategy counts. Idle sessions auto-close, so active means genuinely in use.

• Key params: limit (default 20), include_closed (default true).
• Backed by: GET /api/ai-dropzone/sessions

forven_get_session

A session's tagged strategies and recent runs — the answer to what did I try in session X? Defaults to this client's active session.

• Key params: optional session_id.
• Backed by: GET /api/ai-dropzone/sessions/<session_id>

Write tools

forven_create_session

Optional. Open a labelled session up front. Usually unnecessary — one opens on your first write.

• Key params: label, optional actor, objective.
• Returns: a session with an id like ADZ-0007, now the active session.
• Backed by: POST /api/ai-dropzone/sessions

forven_close_session

Close a session early. Idempotent, and it happens automatically on disconnect. Defaults to the active session.

• Backed by: POST /api/ai-dropzone/sessions/<session_id>/close

forven_register_strategy_file

Step 4 — register a strategy .py you wrote into the workspace. file_path must be absolute.

• Key params: file_path, optional session_id.
• Returns: strategy_id and stage: quick_screen if it certifies; otherwise archived with an untestable_reason (a crash, a look-ahead leak, failed certification) — fix the file and register it again.
• Gotchas: re-registering a TYPE_NAME that's still active is rejected. Logic edits don't need re-registration — code loads live on the next backtest — but changed default_params need a new file with a new TYPE_NAME. If the AST safety gate rejects the file, the hint names what to remove (banned imports such as os or subprocess, dynamic exec/eval).
• Backed by: POST /api/strategies/intake/register-file

forven_create_strategy

Create a strategy from a built-in execution family (for example rsi_momentum) instead of a custom file.

• Key params: strategy_type, symbol, timeframe, parameters; optional name and hypothesis_id (links the strategy to an idea).
• Returns: a strategy_id.
• Backed by: POST /api/backtesting/strategies

forven_run_backtest

Step 5 — backtest.

• Key params: strategy_id, dataset_id ('SYMBOL-TIMEFRAME', such as 'BTC/USDT-1h'); optional session_id, parameters (this run only), timeframe, start / end, leverage, trade_mode, data_venue, compact (default true).
• data_venue picks the stored candles: canonical (the default — the Binance USD-M research data) or a stored venue series such as hyperliquid:perp or okx:spot. Other data streams stay canonical, and a venue run never promotes.
• Returns: the compact payload by default; pass compact=false, or use forven_get_result, for trades and the equity curve.
• Backed by: POST /api/backtesting/run

parameters are for exploration only and never change default_params. The gates judge the registered file's defaults, so bake winners into the file.

forven_run_optimization

Step 6 — parameter search. Persisted optimization evidence is itself a paper-gate requirement. When it finishes, bake the winning parameters into the file's default_params. Declare a small parameter_space() in the file (2–3 parameters, 2–4 values each). A Drop Zone strategy without one is searched over ×0.8, ×1.0 and ×1.2 of up to three numeric defaults, and the deflated Sharpe is charged every combination tried.

• Key params: strategy_id, dataset_id; optional parameter_ranges, objective, n_trials, timeframe, start, end.
• Backed by: POST /api/backtesting/optimize

forven_run_robustness

Step 7 — submit the persisted validation suite, the artifacts the paper gate reads. Transient probes don't count.

• Key params: strategy_id; optional dataset_id (defaults to the strategy's own market), tests (default walk_forward, cost_stress, param_jitter; also monte_carlo and regime_split), baseline_result_id (defaults to the strategy's latest backtest).
• cost_stress reruns that baseline's own window at 2× fees and slippage; param_jitter, monte_carlo and regime_split need a baseline backtest.
• Every test needs a saved verdict before paper. Under the default research door a FAIL is recorded and judged again at paper → live rather than blocking the paper hop; a loss under 2× costs still blocks it.
• Returns: the submitted run for each test (poll each with forven_get_robustness_result), any per-test errors, and a next hint.
• Backed by: POST /api/robustness/<test>/submit — walk-forward, cost-stress, param-jitter, monte-carlo, regime-split

forven_promote_strategy

Attempt a non-forced promotion. Returns structured failed_gates and passed: false when the gates block it.

• Key params: strategy_id, to_status; optional from_status, reason, force (default false — leave it).
• Backed by: POST /api/strategies/<id>/promote

forven_start_paper_session

Final step — promote a gauntlet strategy to paper through the normal gate. Call it only when the gate report shows promotion_ready: true with no failed gates, or when the only failed gate is holdout_pending: that attempt submits the one-shot held-back test, whose verdict then decides.

• Key params: strategy_id; optional reason, force (default false).
• With the default research door the held-back test isn't part of this hop, so holdout_pending only shows here under Strict paper (or with Held-back test runs at set to Gauntlet to paper). If the paper pool is full, the attempt returns paper_queue_full: the strategy waits in the queue and is admitted when a slot frees.
• Gauntlet → paper promotion is automatic by default, so a gate-passer usually reaches paper (or the queue) without this call.

forven_run_gauntlet_candidate

A shortcut for steps 5, 7 and 8 on a promising candidate: a compact persisted backtest, an optional robustness submission, then a non-forced promotion attempt from quick_screen to gauntlet.

• Key params: strategy_id, dataset_id; optional parameters, trade_mode, session_id, run_robustness (default true), robustness_tests, force (default false).
• Returns: {backtest, robustness, promotion}. Poll the robustness result ids, then read the gate report for the paper hop.

The compact backtest payload

By default forven_run_backtest returns only gate-relevant metrics, with the trades and equity curve stripped — built for fast iteration. Illustratively:

{
  "result_id": "R-001234",
  "strategy_id": "S00812",
  "symbol": "BTC/USDT",
  "timeframe": "1h",
  "start_date": "2024-01-01",
  "end_date": "2026-03-31",
  "in_sample":     { "sharpe": 1.4, "max_drawdown_pct": 18.0, "total_trades": 212 },
  "out_of_sample": { "sharpe": 0.9, "max_drawdown_pct": 22.0, "total_trades": 64 },
  "trade_count": 64,
  "session_id": "ADZ-0007"
}

The numbers are placeholders. Trust out_of_sample over in_sample — see metrics. Backtest windows end at the held-back cutoff, so the most recent months are never in a research result.

Gates, and why not to force

Every promotion tool defaults to force=false, which respects the gate system. A blocked attempt returns a failed_gates list rather than an error. A gate-report entry looks like:

{ "id": "walk_forward", "message": "Validation artifact missing", "severity": "block", "actionable": "run_validation_suite", "reason_code": null }

The server's instructions to clients are blunt: never pass force=true to skip a gate. A forced pass can push an unsuitable strategy into paper and poison the paper roster. When a gate fails, next_actions says what to run instead. Going live is never reachable over MCP without your typed GO LIVE in the app.

A minimal loop

1. forven_get_context(), then forven_get_context(section="template") and section="gotchas".
2. forven_get_quant_skills(regime="trending"), and forven_get_data_readiness(symbol="BTC/USDT", timeframe="1h", streams=["funding"]) if the idea uses funding.
3. Write a strategy .py into the workspace from step 1.
4. forven_register_strategy_file(file_path=<absolute path>) — note the strategy_id and stage.
5. forven_run_backtest(strategy_id, dataset_id="BTC/USDT-1h"), and iterate.
6. forven_run_optimization(strategy_id, dataset_id="BTC/USDT-1h"), then bake the winners into default_params.
7. forven_run_robustness(strategy_id), then poll forven_get_robustness_result.
8. forven_get_gate_report(strategy_id); when it's green — or only holdout_pending is left, which on this hop happens only when the held-back test runs before paper — forven_start_paper_session(strategy_id).

Registration returns a strategy_id and a stage; backtests return the compact payload; robustness runs move from running to succeeded with a verdict; and the gate report lists what's missing until promotion_ready turns true. A paper_queue_full answer means the strategy passed and is waiting for a paper slot. Watch it live on Integrations → AI Clients.

Good to know

• Absolute paths only. forven_register_strategy_file rejects relative paths; build the path from forven_get_context.
• Closed sessions are final. New work gets a new session.
• Overrides are per run. parameters in forven_run_backtest never change default_params.
• The backend must be up. Every tool is an HTTP client: a stopped backend means connection refused, and missing keys with auth on means 401. See troubleshooting.

Related

• MCP server — connect a client and check the tools appear
• AI Drop Zone — the page these tools drive
• Promotion gates — what blocks a non-forced promotion
• Troubleshooting — timeouts, 401s and connection errors