flox-mcp — Model Context Protocol server for FLOX

Gives AI agents (Cursor, Claude Code, Cline) grounded access to the FLOX C-API surface, error catalog, and indicator library — so they can write code against real signatures instead of guessing.

The server runs locally on the developer's machine; the IDE spawns it as a child process and talks to it over stdio. There is no public hosting; nothing leaves the machine.

Tools

Quickstart

pip install flox-mcp           # MCP server + flox-py (indicators, backtest, engine CLI)
flox-mcp init                  # writes ./.mcp.json for the current project
# restart your MCP client (Claude Code / Cursor / Cline) → done

You get the whole surface in one install: docs / lookup tools, indicator introspection, backtest, and the engine CLI (flox engine sim, flox tape record). For tier-5/6 (live state, place_order, flatten_positions), also start a paper engine and rerun init with the printed token:

flox engine sim --strategy s.py --tape ./tape       # prints engine URL + token
flox-mcp init --engine-url URL --token T            # appends env to ./.mcp.json

flox engine sim boots a Runner + SimulatedExecutor + ControlServer and writes a runtime snapshot the read tools poll. See python/flox_py/engine_cli.py for the full set of flags.

flox engine sim boots a Runner + SimulatedExecutor + ControlServer and writes a runtime snapshot the read tools poll. See python/flox_py/engine_cli.py for the full set of flags.

flox-mcp init flags

Manual override

If you'd rather hand-edit, the resulting .mcp.json is shaped like:

{
  "mcpServers": {
    "flox": {
      "command": "flox-mcp",
      "args": ["serve"],
      "env": {
        "FLOX_RUNTIME_STATE": "$HOME/.flox/runtime.json"
      }
    }
  }
}

Same shape works for Claude Code, Cursor, and Cline — they all read mcpServers.<name> from a project-local .mcp.json (or the client-specific global path).

Develop

cd mcp
pip install -e ".[dev]"

# Run the server manually (stdio):
flox-mcp

# Run unit tests:
pytest tests/

# Sync bundled data from canonical sources (.api/, docs/errors/):
python ../scripts/sync_mcp_data.py

Bundled data

Read-only copies in the wheel:

• flox_mcp/data/c-api.snapshot — copy of .api/c-api.snapshot.
• flox_mcp/data/errors/E_*.md — copies of docs/errors/E_*.md.
• flox_mcp/data/ir.snapshot.json — IR (functions, structs, enums, typedefs, function pointers) pulled from the IDL spec via libclang. Versioned schema.
• flox_mcp/data/binding_manifest.json — per-binding symbol map keyed by IDL group. Built from binding_parity.yaml plus scans of flox_py/_flox_py/__init__.pyi, node/index.d.ts, and the codon golden file.
• flox_mcp/data/examples_index.json — index of docs/examples/ (path, language, topic, sha256).
• flox_mcp/data/docs.fts.sqlite — SQLite FTS5 index over six doc roots: bindings, how-to, tutorials, reference, explanation, errors. Anything outside that list is skipped at index build time. Private trackers and CLAUDE.md are not in the allowlist.
• flox_mcp/data/templates/strategy/{python,node}/{bar,trade,hybrid}-driven.tmpl — strategy scaffolds rendered by scaffold_strategy.

scripts/sync_mcp_data.py --check runs in CI. Any drift between a bundled copy and its canonical source fails the build. To update after editing a canonical source: run the script without --check and commit the diff.

The flox-mcp package version is bumped in lockstep with flox-py and @flox-foundation/flox by scripts/set-version.sh. An installed flox-mcp x.y.z was built from the same source tree as the matching flox-py / npm release, so what the agent sees lines up with what the developer has installed.

Scope notes

• The server is local. No network calls. AI clients spawn it as a child process and talk via stdio.
• Most tools are read-only data lookups. The two that execute code — compute_indicator and run_backtest — run in-process / in a resource-limited subprocess respectively. run_backtest is an MVP sandbox: it caps CPU, memory, and output size, but does NOT isolate filesystem or network. Wrap with nsjail / firejail / Docker for any deployment that takes untrusted input.
• The snapshot used by list_capi_functions is the same .api/c-api.snapshot enforced by the codegen ABI gate; the IR snapshot used by lookup_symbol / list_bindings is regenerated from the same IDL spec on every release. So the agent's view of the surface tracks what FLOX actually ships.

License

MIT — same as FLOX.