MCP server

The Forven MCP server is a Model Context Protocol endpoint that exposes the AI Drop Zone as a set of tools. An MCP client — Claude Desktop, an IDE plugin, or any compliant agent — connects to it and can read workspace context, write strategy files, register them, run backtests, and attempt pipeline promotions without you copying anything in or out by hand.

This page is for developers and operators wiring up a client. It covers what the server is, how to connect it, how to verify the tools appear, and the end-to-end strategy-generation loop. For the full tool catalog and parameter shapes, see the MCP tools reference.

What the server is

The MCP server is a separate, stdio-based process. Your MCP client spawns it on startup, and the server in turn acts as an HTTP client of your running Forven backend (default http://127.0.0.1:8003). It does not hold strategy state or a database of its own — every tool call is forwarded to a backend REST endpoint and the result is returned to the agent.

That means two processes must both be alive:

1. The Forven backend — the local FastAPI server, running because the desktop app is open or because you started it directly.
2. The MCP server — python -m forven.mcp_server, spawned by your client.

The agent talks to the MCP server over stdio (JSON-RPC). The MCP server talks to the backend over HTTP. Your model provider keys, market data, and SQLite store never leave your machine; the MCP layer only moves tool calls and results.

What it exposes

The server registers tools prefixed forven_* that map onto AI Drop Zone and lifecycle operations. The headline ones:

• forven_get_context — returns the workspace path, strategy template, available datasets, canonical parameter rules, and the step-by-step workflow. Call this first in any task.
• forven_get_quant_skills — loads curated quant skills (what has worked per regime) before you design anything.
• forven_register_strategy_file — registers a .py file you wrote into quick_screen.
• forven_run_backtest — backtests a registered strategy on a dataset such as BTC/USDT-1h.
• forven_promote_strategy / forven_run_gauntlet_candidate — attempt lifecycle promotion, respecting promotion gates unless explicitly forced.
• Session tools (forven_create_session, forven_get_session, forven_close_session) for tagging work into an ADZ-#### session.

The complete list of tools — there are 19 — is documented in the MCP tools reference.

Connecting a client

You configure the server in your MCP client's config file. For Claude Desktop that is claude_desktop_config.json; a project-scoped .mcp.json works the same way. The block registers a server named forven.

Steps

1. Make sure the backend is running. Open the Forven desktop app, or start the backend directly:

   python -m uvicorn forven.api:app --port 8003

   Confirm it answers on http://127.0.0.1:8003.

2. Find two absolute paths. You need the absolute path to the Python interpreter in your Forven virtualenv, and the absolute path to the repo root (for PYTHONPATH). Relative paths fail, because the client spawns the server from its own working directory.

3. Add the server block to claude_desktop_config.json (or .mcp.json). On Windows it looks like this:

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

   On macOS the command is a POSIX path such as ~/.venv/bin/python and PYTHONPATH points at the repo directory.

4. Add auth keys only if your backend requires them. If FORVEN_AUTH_REQUIRED=true on the backend, add the keys to the env block:

   "env": {
     "PYTHONPATH": "C:\\Users\\you\\projects\\forven",
     "FORVEN_API_URL": "http://127.0.0.1:8003",
     "FORVEN_API_KEY": "your-api-key",
     "FORVEN_OPERATOR_KEY": "your-operator-key"
   }

   If auth is off (the default for a purely local setup), you can omit both.

5. Restart the client. Tools do not appear until the client re-reads its config. Fully quit and reopen Claude Desktop.

6. Verify the tools loaded (see below).

What you'll see

After restart, your client lists a forven server with its tools available — names like forven_get_context, forven_run_backtest, and forven_promote_strategy. Ask the agent to call forven_get_context; a healthy connection returns a structured context object containing the workspace path, the strategy template, dataset ids, and the workflow steps. If that call succeeds, the wiring is correct.

Configuration reference

The mcpServers.forven block accepts these keys. command and PYTHONPATH have no defaults — you must set them.

These map onto the same environment variables the backend uses for auth, so keep the keys consistent between the two processes.

The strategy-generation loop

The minimal loop an agent runs over MCP. Stages use the real pipeline names — quick_screen (the public site calls this "screen"), gauntlet, then paper (the public synonym is "candidate"), then live.

1. Call forven_get_context to learn the workspace path, template, datasets, and endpoints.
2. Call forven_get_quant_skills(regime='trending') (or range_bound / volatile) to check what has historically worked.
3. Write a strategy .py file to the workspace directory from the context (typically forven/strategies/custom/).
4. Call forven_register_strategy_file(file_path=<absolute_path>). The path must be absolute. The response includes a strategy_id and a stage — quick_screen if it matches a certified execution family, research_only otherwise.
5. Call forven_run_backtest(strategy_id, dataset_id='BTC/USDT-1h'). Read the metrics. For rapid iteration pass compact=true to strip trades and equity curves and return only gate-relevant metrics.
6. Iterate: edit the .py and re-register, or start a new idea. Parameter overrides in a backtest are one-shot — they do not persist to the strategy's defaults.
7. When the evidence is there, call forven_promote_strategy(strategy_id, to_status='gauntlet'). Gates are checked and any failures are returned as a structured failed_gates array.

Promotion is never silent. A non-forced call respects the gauntlet and the gate rules; force=true bypasses them, which can let an unsuitable strategy into paper. Prefer non-forced and read the gate report.

Sessions

Wrap a run of related work in a session so you can ask "what did I test here?" later. Call forven_create_session(label='RSI mean reversion v3') to get an id like ADZ-0007, pass that session_id to your register and backtest calls, then forven_close_session('ADZ-0007') when you're done. Closed sessions are immutable — tag work up front. The AI Drop Zone page covers sessions in depth.

Caveats

Honest rough edges to expect during beta:

• Connection refused / 401. The MCP server is useless without a live backend. If the backend is down or on a different port, every tool call fails with Connection refused. If FORVEN_AUTH_REQUIRED=true but the keys are missing from the MCP env, every call returns 401 Invalid or missing operator key. Check FORVEN_API_URL and the keys first.
• Tool-call timeouts. Backtests on cold caches and long gauntlet runs can exceed the default 60s. Raise FORVEN_MCP_TIMEOUT if you see Tool call timed out.
• Tools don't appear. The client must be restarted after any edit to claude_desktop_config.json or .mcp.json. Tools never hot-reload.
• forven not importable. Almost always a missing or wrong PYTHONPATH. It must be the absolute repo root.
• Logs. On Windows, the client writes a per-server log to %APPDATA%\Claude\logs\mcp-server-forven.log. Read it when a tool call misbehaves.

The full diagnostic walkthrough lives on the troubleshooting page.

Related

• MCP tools reference — every forven_* tool, its parameters, and return shape.
• AI Drop Zone — the workspace and session model the tools drive.
• Environment variables — backend auth keys and ports.
• Troubleshooting — connection, timeout, and 401 fixes.