MCP tools reference

This is the developer reference for every tool the Forven MCP server exposes. If you only want to connect a client and start working, read MCP server first — this page assumes the server is already running and visible to your client.

The server surfaces Forven's AI Drop Zone as 19 MCP tools. Each tool is a thin HTTP client over the running Forven backend (FORVEN_API_URL, default http://127.0.0.1:8003), so every call you make here does exactly what the equivalent UI action or REST endpoint does — nothing more, nothing less. The same promotion gates apply.

How to read this reference

• Tool name — the exact string your MCP client calls (all tools are prefixed forven_).
• Purpose — what it does and when to reach for it.
• Key params — the parameters that matter; optional ones are noted.
• Returns — the shape you get back.
• Backed by — the REST endpoint it calls, for cross-referencing.

A note on names. The real strategy stages are quick_screen → gauntlet → paper → live. The public site calls paper trading "candidate" — same thing; this reference uses the real stage names the tools accept.

Tool catalog

The 19 tools group into five jobs: context & insight, sessions, registration & backtest, robustness & optimization, and lifecycle & gates.

Context & insight

forven_get_context

Return the full AI Drop Zone context: workspace path, strategy template, available datasets, API endpoints, canonical parameter rules, and the step-by-step workflow. Call this first in any new task — it tells you the absolute file_location where strategy .py files must be written.

• Key params: none.
• Returns: a structured context dict (workspace/file_location, template, dataset list, execution families, param naming rules, workflow steps).
• Backed by: GET /api/ai-dropzone/context

forven_get_quant_skills

Load curated, market-regime-specific insights before you design a strategy. Past survivors leave hints here. See quant skills for how the store is built.

• Key params: optional regime (trending | range_bound | volatile), skill_type, min_confidence (default 0.5), limit (default 10).
• Returns: a list of insights with what works / what doesn't, a confidence score, sample size, and regime classification.
• Backed by: GET /api/quant-skills

forven_list_strategies

List registered strategies, optionally filtered by status. Use it to see what is already in the lab.

• Key params: optional status (e.g. active, archived).
• Returns: a list of strategy records.
• Backed by: GET /api/strategies

forven_get_recent_runs

Return the last N backtest runs across all strategies.

• Key params: optional limit.
• Returns: a list of recent run summaries.
• Backed by: GET /api/backtesting/runs

forven_get_result

Fetch one backtest result by result_id — full metrics, trades, and config. Use it after forven_run_backtest to inspect an outcome in detail.

• Key params: result_id.
• Returns: the full result payload (metrics, trades, config).
• Backed by: GET /api/results/{result_id}

Sessions

Sessions (ADZ-####) are optional grouping tokens that tag your registrations and runs so you can later ask "what did I try in iteration 7?". They are recommended but never required.

forven_create_session

Open a new session for grouping subsequent register-file and backtest calls.

• Key params: label, optional actor, objective.
• Returns: a session record with an id like ADZ-0007 — pass it as session_id in later calls.
• Backed by: POST /api/ai-dropzone/sessions

forven_list_sessions

List recent sessions with strategy counts.

• Key params: optional include_closed (pass false for only-open), limit.
• Returns: a list of session summaries.
• Backed by: GET /api/ai-dropzone/sessions

forven_get_session

Fetch one session's detail — its tagged strategies and recent runs.

• Key params: session_id.
• Returns: session detail (tagged strategies, recent backtest runs).
• Backed by: GET /api/ai-dropzone/sessions/{session_id}

forven_close_session

Mark a session closed. Idempotent.

• Key params: session_id.
• Returns: confirmation. A closed session is immutable — you cannot reopen or modify it.
• Backed by: POST /api/ai-dropzone/sessions/{session_id}/close

Registration & backtest

forven_register_strategy_file

Register a single Python strategy file you wrote into the workspace. The file_path must be absolute — forven_get_context gives you the workspace path to build it from.

• Key params: file_path (absolute), optional session_id.
• Returns: strategy_id and stage — quick_screen if the file uses a pre-certified execution family, research_only otherwise — plus a certification summary.
• Backed by: POST /api/strategies/intake/register-file

forven_create_strategy

Create a certified strategy container using a built-in execution family (for example rsi_momentum). Use this instead of register-file when the strategy should reuse an existing family rather than a custom .py file.

• Key params: hypothesis_id, strategy_type (the execution family), symbol, timeframe, parameters, optional name.
• Returns: a strategy_id for the new container.
• Backed by: POST /api/backtesting/strategies

forven_run_backtest

Run a backtest for a registered strategy on a dataset.

• Key params: strategy_id, dataset_id (format 'BTC/USDT-1h' — symbol-timeframe), optional session_id, parameters (overrides default params for this run only), timeframe, start / end, leverage, trade_mode, compact.
• Returns: the full backtest payload (metrics, trades, config) — or, with compact=true, the compact payload.
• Backed by: POST /api/backtesting/run

Parameter overrides do not persist into the strategy's default_params. Each backtest is independent; to change defaults permanently use the lifecycle params endpoint or the UI.

Robustness & optimization

forven_run_optimization

Run parameter optimization (grid / Bayesian search) for a registered strategy. Use it before the gauntlet when you need parameter-search evidence.

• Key params: strategy_id, dataset_id, optional parameter_ranges, objective, n_trials, date range.
• Returns: optimization results.
• Backed by: POST /api/backtesting/optimize

forven_run_verdict

Run robustness / verdict tests for a strategy and dataset — the same battery the gauntlet uses — to gather evidence for skeptical gates.

• Key params: strategy_id, dataset_id, optional tests (walk_forward, parameter_stability, cost_stress, monte_carlo).
• Returns: verdict results that inform gate readiness.
• Backed by: POST /api/backtesting/verdict/run

Lifecycle & gates

These tools move (or inspect) a strategy along quick_screen → gauntlet → paper → live. Read-only inspection never changes state. See promotion gates for what each gate checks.

forven_get_gate_report

Inspect a strategy's current readiness without attempting promotion. Read-only.

• Key params: strategy_id.
• Returns: current lifecycle state, the latest compact backtest metrics, latest_gate_failure (if any), the full failed_gates list, and a promotion_ready boolean. Always compact.
• Backed by: GET /api/strategies/{strategy_id}/container and GET /api/lifecycle/strategies/{strategy_id}/readiness

forven_get_paper_readiness

Read the current state and latest evidence for paper readiness. Does not promote.

• Key params: strategy_id.
• Returns: readiness state and supporting evidence.
• Backed by: the lifecycle readiness endpoint.

forven_promote_strategy

Attempt a lifecycle promotion. Non-forced by default — the real gate system can block it.

• Key params: strategy_id, to_status, optional from_status, reason, force (default false).
• Returns: a promotion result, or a structured failed_gates array ({id, message, severity}) when blocked. Severity is block or warning.
• Backed by: POST /api/strategies/{strategy_id}/promote

forven_start_paper_session

Shorthand to promote a gauntlet strategy to paper through the normal lifecycle gate. Defaults to non-forced.

• Key params: strategy_id, optional force.
• Returns: the promotion result (or failed_gates).
• Backed by: the promote endpoint (to_status='paper').

forven_run_gauntlet_candidate

Orchestrate a full candidate evaluation in one call: a compact backtest, optional verdict tests, then a non-forced gauntlet promotion attempt.

• Key params: strategy_id, dataset_id, optional run_verdict, verdict_tests, force (default false).
• Returns: {backtest: {...}, verdict: {...}, promotion: {...}} — all three in one response.
• Backed by: composes the backtest, verdict, and promote endpoints.

The compact backtest payload

forven_run_backtest(..., compact=true) and every gate-report tool return the compact payload: gate-relevant metrics only, with the bulky trades array and equity curve stripped out. It is built for rapid iteration, CI gates, and feeding backtest results into a multi-step evaluation loop.

It carries, illustratively:

{
  "result_id": "R-001234",
  "strategy_id": "S-000812",
  "in_sample":     { "sharpe": 1.4, "max_drawdown": 0.18, "trade_count": 212 },
  "out_of_sample": { "sharpe": 0.9, "max_drawdown": 0.22, "trade_count": 64 },
  "failed_gates": [],
  "passed": true
}

The numbers above are placeholders. Trust the out_of_sample block over in_sample — in-sample metrics flatter a strategy. See metrics for what each field means. Use compact=false (the default) when you want trades, fills, and the equity curve for detailed analysis.

Forced vs non-forced promotion

Every promotion tool defaults to force=false, which respects the gate system.

• Non-forced (force=false) — gates run. If a strategy falls short on Sharpe, trade count, robustness, max drawdown, parameter stability, or Monte-Carlo results, the call returns a structured failed_gates array and the strategy stays put.
• Forced (force=true) — gates are bypassed. This can push an unsuitable strategy into paper and defeats the point of the pipeline. Use it only for deliberate, audited overrides.

A failed_gates entry looks like:

{ "id": "min_sharpe", "message": "OOS Sharpe 0.4 below floor 0.8", "severity": "block" }

severity is block (hard stop) or warning (advisory). The gate names and messages are parsed from the backend's lifecycle reporting — the same checks the gauntlet and gate report apply.

A minimal generation loop

This is the smallest end-to-end flow a client runs against these tools.

Steps

1. Call forven_get_context to learn the workspace path, template, datasets, and endpoints.
2. Call forven_get_quant_skills(regime='trending') to check what has worked historically in that regime.
3. Write a strategy .py file to the workspace directory from step 1.
4. Call forven_register_strategy_file(file_path=<absolute path>) to register it — note the returned strategy_id.
5. Call forven_run_backtest(strategy_id, dataset_id='BTC/USDT-1h', compact=true) and read the gate-relevant metrics.
6. Iterate: edit the file and re-register, or try a new idea.
7. When the evidence holds up, call forven_promote_strategy(strategy_id, to_status='gauntlet') to attempt promotion. Gates are checked; failures come back structured.

What you'll see: registration returns a strategy_id and a stage (quick_screen or research_only); backtests return the compact payload with a passed boolean; a blocked promotion returns a failed_gates array rather than an error. Watch the run land in the AI Drop Zone and the strategy advance in the pipeline.

Caveats

• Absolute paths only. forven_register_strategy_file rejects relative paths; build the path from forven_get_context.
• Closed sessions are immutable. Tag work upfront or open a new session — you cannot reopen ADZ-#### once closed.
• Overrides are per-run. parameters in forven_run_backtest never mutate default_params.
• The backend must be up. Every tool is an HTTP client; if the backend is down or on the wrong port you'll get Connection refused or 401. See troubleshooting for connection, auth, and timeout fixes.

Related

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