Skip to content

Use Monte-Neo from coding agents

Monte-Neo ships an MCP server, monte-neo-mcp, so Claude Code, Codex, Gemini CLI, Cursor and any other MCP client can verify a strategy before reporting it. The server runs locally over stdio and reads files from your project.

Requirements: uv (for uvx) and Python 3.11+.

What has been tested

Agent Tested by the maintainer Notes
Claude Code Yes MCP server, plugin and monte-neo bench run
Qwen Code with a local model (Ollama) Yes MCP server and bench run --base-url; see Local agents
Codex CLI No config in integrations/codex, never run by the maintainer
Gemini CLI No config in integrations/gemini, never run by the maintainer
Cursor No config in integrations/cursor, never run by the maintainer
Other MCP clients (Cline, Continue, Goose, Aider, OpenHands, Windsurf, Zed, VS Code agent mode, ...) No the same stdio MCP server; unverified

"No" means nobody has reported a run, not that it fails. If you have one of these agents installed, please run the 10-minute test in issue #114 and report the result, whatever it is. Each report with the agent's version gets a row here with a link.

MCP tools

Tool Purpose
verify_strategy Full verification, returns a strategy-verdict/1 certificate
verify_grid Runs the parameter search inside the verifier (counts n_trials) and adds walk-forward, parameter-plateau and PBO checks
validate_alpha A cross-sectional score: does it predict returns (rank IC, decay, quantiles, placebos), and can its long-short portfolio be traded (impact, capacity, shorts, rebalance day)? alpha-report/1
verify_returns A track record given only as returns: smoothing, missing small losses, implausible consistency, significance with the manager's number of strategies
verify_legs A spread, pairs or stat-arb strategy given by the quantity held in each leg: re-derives the P&L and fails accounting_mismatch when the reported return is not what the legs earned (phantom mean reversion from a rolling hedge ratio)
repair_strategy Repairs defects without overfitting (choice by defects on 70 % of the history, lockbox opened once): REPAIRED, REPAIRED_NO_EDGE, NOT_REPAIRABLE or NOTHING_TO_REPAIR
build_dossier A certificate as a validation dossier folder for a committee: framework map (SR 11-7, SS1/23, RTS 6), limitations, reproduction, sign-off
monitor_live After launch: live against backtest, realised slippage, alpha-death alarms
verify_quotes Intraday strategies on bid/ask quotes: does the profit survive the time the quotes arrived (stamp + latency)? Arrival look-ahead, latency scan and latency Monte Carlo
probe_lookahead Look-ahead probes only (lint, outside data, truncation, perturbation, determinism); works on universes too
cost_stress Break-even cost and returns under 0, 1 and 2 bars of execution delay
recheck_certificate Reproduces a certificate from its original data and strategy or signals
check_signature Checks a certificate's Ed25519 signature, optionally against the issuer's public key
render_report Writes a certificate as a self-contained HTML report for people (equity vs buy & hold, checks, periods)
verdict_schema JSON schema of the certificate
verifier_manifest Execution semantics and the check catalogue

All tools take file paths:

  • OHLCV as .csv or .parquet.
  • A strategy .py file that defines signal(df), or a positions file.

Claude Code

Recommended: install the plugin. It bundles the MCP server, the verify-strategy skill and the /verify command.

/plugin marketplace add NeoZorK/Monte-Neo
/plugin install monte-neo@monte-neo

The plugin includes a PostToolUse hook. When Claude writes or edits a Python file that looks like strategy or backtest code, the hook reminds it to verify before reporting results. It fires once per file per session and never blocks an edit.

MCP server only:

claude mcp add monte-neo -- uvx --from "monte-neo[mcp]>=0.53.0" monte-neo-mcp

Codex (OpenAI)

Append integrations/codex/config.toml to ~/.codex/config.toml. Then copy the rules from integrations/codex/AGENTS.md into your project's AGENTS.md.

Gemini CLI

Copy integrations/gemini/ to ~/.gemini/extensions/monte-neo/. The extension registers the MCP server and loads GEMINI.md as context.

Qwen Code (and local models)

qwen mcp add monte-neo uvx --from "monte-neo[mcp]>=0.53.0" monte-neo-mcp, and copy integrations/qwen/QWEN.md into your project. Qwen Code can also drive a model served on your machine: see Local agents.

Claude Code: "There's an issue with the selected model"

This message comes from Claude Code, not from Monte-Neo, and it appears even after a successful /login when a variable in your shell overrides the login: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL or ANTHROPIC_MODEL (a token or a gateway from the shell wins over the login, and it may not serve the model you picked).

Look at the names of the variables (never paste their values anywhere):

env | grep -i -E '^(ANTHROPIC|CLAUDE)' | cut -d= -f1

Start Claude Code without them, for this window only:

env -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL -u ANTHROPIC_MODEL claude

If that works, remove the variables from your shell profile (~/.zshrc) or keep using the command above. Inside a session, /status shows the login method and the model in use.

monte-neo bench run does the same for the agents it starts: add --clean-env to run them without these four variables, so each agent uses its own login. It is off by default, because some setups need a token or a gateway on purpose.

Cursor

  1. Copy integrations/cursor/mcp.json to .cursor/mcp.json in your project, or merge it into your existing .cursor/mcp.json.
  2. Copy integrations/cursor/rules/monte-neo-verify.mdc to .cursor/rules/.

Other MCP clients

Use this stdio command:

uvx monte-neo mcp          # v0.20.0+: the MCP SDK is a default dependency
# older pin: uvx --from "monte-neo[mcp]>=0.49.0" monte-neo-mcp

Monte-Neo is published to the official MCP Registry as io.github.NeoZorK/monte-neo (server.json), so registry-aware clients can install it by name.

For HTTP clients, add --transport streamable-http.

GitHub Actions

The quickest way: run monte-neo init-ci in your project. It finds your strategy file and price table, and writes .github/workflows/monte-neo.yml (checkout pinned to a commit, the action pinned to the release you have installed, a verdict comment on pull requests, the certificate uploaded as an artifact). Options: --n-trials, --fail-on, --isolate, --sign, --out, --print (show it without writing), --force. It never overwrites a file without --force. Comments on pull requests from forks are not possible (GitHub gives those runs a read-only token); the verdict is still in the job summary. By hand:

- uses: NeoZorK/Monte-Neo@v0.54.0
  with:
    ohlcv: data/btc_1h.csv
    strategy: strategies/momentum.py
    n-trials: "12"

The job fails on REJECT. To also fail on NEEDS_MORE_EVIDENCE, set fail-on: NEEDS_MORE_EVIDENCE. The step summary shows every check. The verdict and certificate outputs can feed later steps.

Optional inputs:

  • grid: '{"fast": [10, 20], "slow": [80, 120]}' runs verify_grid instead of a single verification.
  • claim: claim.json (a file or JSON text such as '{"sharpe": 2.1, "total_return": 0.85}') checks the numbers your report claims against the verified ones; an overclaim fails the job's verdict to NEEDS_MORE_EVIDENCE.
  • comment: "true" posts the verdict as a PR comment and updates the same comment on later runs. The job needs the pull-requests: write permission.
  • signing-key: ${{ secrets.MONTE_NEO_SIGNING_KEY }} signs the certificate with Ed25519. The key-id output and the step summary show which key signed it.
  • upload-certificate: "true" uploads the certificate as the monte-neo-certificate workflow artifact.

Signing certificates in CI

  1. Create a key pair locally: pip install "monte-neo[sign]" and monte-neo verify --keygen ci.
  2. Store the content of ci.key as the repository secret MONTE_NEO_SIGNING_KEY (Settings → Secrets and variables → Actions). Delete the local copy if you do not need it.
  3. Publish ci.pub, for example in your README. Anyone can then check a certificate from your CI: monte-neo verify --check-signature verdict.json --public-key ci.pub.

The action writes the key to a temporary file that only the runner user can read, and deletes it right after signing. Pull requests from forks do not receive repository secrets, so their certificates are not signed.

Writing a strategy file

import numpy as np

def signal(df):
    """Positions per row: +1 long, 0 flat, -1 short. Use only rows <= t for bar t."""
    fast = df["close"].rolling(20).mean()
    slow = df["close"].rolling(80).mean()
    return np.where(fast > slow, 1, 0)
  • Use pandas and numpy only. The file runs inside the MCP server's environment.
  • Do not read files or call the network in signal().
  • The file is executed with your permissions.