MCP server

The Forven MCP server is a Model Context Protocol endpoint that exposes the AI Drop Zone as 21 tools. An MCP client — Claude Code, Claude Desktop, Cursor, Codex CLI, or any compliant agent — connects to it and can read the workspace, check data readiness, write and register strategy files, run backtests and optimizations, submit the persisted validation suite, read the gate report, and promote through the real pipeline gates.

This page is for wiring up a client. It also covers the other direction: giving Forven's own agents external MCP tool servers. For each tool's parameters and return shape, see the MCP tools reference.

What the server is

A separate, stdio-based process. Your client spawns it, and it acts as an HTTP client of your running Forven backend (default http://127.0.0.1:8003). It holds no state of its own: every tool call is forwarded to a backend endpoint and the result handed back.

So two things must be running:

1. Forven itself, started the usual way.
2. The MCP server — python -m forven.mcp_server, spawned by your client.

Your keys, data and database never leave your machine; the MCP layer only moves tool calls and results. The client uses its own AI subscription — Forven's agents and model keys aren't involved.

What it exposes

Twenty-one forven_* tools — eleven that only read, ten that write. The ones a client uses most:

• forven_get_context — workspace path, strategy template, datasets, parameter rules and gotchas. Call it first.
• forven_get_quant_skills — curated quant skills, to skip known dead ends.
• forven_get_data_readiness — whether a market has the data a strategy needs (ready, needs_data or blocked), before writing one that reads anything beyond candles.
• forven_register_strategy_file and forven_create_strategy — add a strategy from a file, or from a built-in execution family.
• forven_run_backtest and forven_run_optimization — test and tune it.
• forven_run_robustness and forven_get_robustness_result — submit and poll the persisted validation suite the paper gate reads.
• forven_get_gate_report — stage, target_stage, promotion_ready, failed gates with reason codes, and next actions.
• forven_promote_strategy and forven_start_paper_session — promote through the real gates.

Sessions are automatic

A Drop Zone session opens on the first register or backtest call, tags every later call, and closes when the client disconnects. Idle sessions are closed after about 6 hours (FORVEN_DROPZONE_IDLE_TTL_HOURS). forven_create_session still exists if you want a label up front, and passing session_id resumes a specific session.

Connecting a client

The quickest route is Integrations → AI Clients → Connect an MCP client. Pick your client and it shows which file to edit and a ready-to-paste snippet. Supported: Claude Desktop, ChatGPT Desktop, Jan, LibreChat, Minimax Agent, Claude Code, Cursor, Windsurf, VS Code, Cline, Roo Code, Continue.dev, Zed, Codex CLI, Gemini CLI, Warp, and Other / custom. For Claude Code it's one command, run from your Forven folder with its virtual environment active:

claude mcp add forven -- python -m forven.mcp_server

The Connect Claude Code or Cursor walkthrough goes through it step by step.

Steps: Claude Desktop, by hand

{
  "mcpServers": {
    "forven": {
      "command": "C:\\Users\\you\\Forven\\.venv\\Scripts\\python.exe",
      "args": ["-m", "forven.mcp_server"],
      "env": {
        "PYTHONPATH": "C:\\Users\\you\\Forven",
        "FORVEN_API_URL": "http://127.0.0.1:8003",
        "FORVEN_MCP_TIMEOUT": "60"
      }
    }
  }
}

Configuration reference

Without MCP

Clients that can't speak MCP can call the same operations over HTTP. The Connect over HTTP (no MCP) card lists the endpoints, a small CLI (python -m forven.agent) and Python and TypeScript snippets. The tool-to-endpoint mapping is in the tools reference.

The strategy loop

The server's own instructions give the client this loop:

1. forven_get_context (overview first, then the template and gotchas sections) before writing any code.
2. forven_get_quant_skills for priors — and before using any input beyond candles, forven_get_data_readiness for the market.
3. Write a strategy .py into the workspace.
4. forven_register_strategy_file(file_path=<absolute path>). It lands in quick_screen, or is archived with an untestable_reason (a crash, a look-ahead leak, failed certification) — fix the file and register again.
5. forven_run_backtest, and iterate on the design.
6. forven_run_optimization, then bake the winning parameters into the file's default_params.
7. forven_run_robustness — the persisted suite (walk-forward, cost stress, parameter jitter) the paper gate reads — and poll forven_get_robustness_result.
8. forven_get_gate_report, then forven_promote_strategy when every gate is green, or when the only failed gate is holdout_pending — that attempt submits the one-shot held-back test, whose verdict then decides. By default the held-back test runs at paper → live, so on the way into paper you'll only see holdout_pending under Strict paper or with Held-back test runs at set to Gauntlet to paper.

Never pass force=true to skip a gate. A genuine rejection is the system working, and the gate report says exactly what's missing. For a strategy already in paper, the gate report checks the paper → live gate, and its next action says live needs your typed GO LIVE — the client shouldn't try to promote it.

What "promote" means with the default settings: gauntlet → paper goes through the research door, which admits a strategy that isn't broken or clearly losing and only records the selection-bias checks (deflated Sharpe, walk-forward fold rate, regime split, jitter, robustness score). Those are enforced at paper → live, together with the sequential forward-evidence test, the breadth test and the held-back test — so holdout_pending on the paper hop only appears when the held-back test runs before paper (Strict paper, or Held-back test runs at → Gauntlet to paper). A strategy that passes the door while the paper pool is full gets paper_queue_full and waits for a slot. See forven_get_gate_report in the MCP tools reference for the reason codes.

External MCP servers for your agents

The other direction: Forven's own agents can call tools from external MCP servers you add — a web search, a filesystem, a ticker API. Most installs never need one.

Diagnostics lists the servers' status once any exist. Deleting a server revokes every agent's grant for it.

Troubleshooting

• Connection refused or 401. The MCP server is useless without a running backend. If FORVEN_AUTH_REQUIRED=true and the keys are missing from env, every call returns 401. Check FORVEN_API_URL and the keys first.
• Tool calls time out. Backtests on a cold cache can take longer than 60 seconds; raise FORVEN_MCP_TIMEOUT.
• Tools don't appear. Restart the client after any config edit; tools never hot-reload.
• forven not importable. Almost always the wrong python (not your Forven virtual environment) or a missing PYTHONPATH.
• Logs. On Windows, Claude Desktop writes %APPDATA%\Claude\logs\mcp-server-forven.log.

More on troubleshooting.

Related

• MCP tools reference — every forven_* tool, its parameters and return shape
• AI Drop Zone — the page and the session model the tools drive
• Agents — tool grants and the toolset matrix for Forven's own agents
• Environment variables — backend auth keys and ports