What simengine MCP server does
The simengine MCP server gives an AI agent access to configurable Monte Carlo decision modeling. A model is described in JSON, including uncertain parameters, operator-controlled variables, external factors, starting state, per-step calculations, accumulators, final metrics, safety rules, and optimization settings. The engine can run 5,000 or more simulated futures for a selected time horizon and score the resulting outcomes.
The system supports common probability models including fixed values, uniform, triangular, normal, lognormal, Bernoulli, Poisson, Student's t, and correlated normal distributions. Configurations can represent business pipelines, portfolios, job searches, project timelines, rental properties, or SaaS growth, while the schema is general enough for other domains.
Risk evaluation includes chance constraints and CVaR constraints. When controls are marked as tunable, the genetic optimizer can search for better outcomes using selection, crossover, mutation, elitism, and tournament selection. Bayesian updating supports Beta-Binomial, Gamma-Poisson, and Normal-Normal conjugate updates for incorporating observed evidence.
How it works
The simengine MCP server uses a JSON configuration as the model contract. Each simulation samples the configured variables, executes the step logic over the requested number of steps, updates accumulators, and calculates final metrics. A random seed can be supplied when reproducible runs are needed.
Diagnostics provide convergence analysis, one-at-a-time sensitivity analysis, and comparison with a deterministic baseline. The project also includes a forecast ledger and calibration workflow using Brier score, log-loss, and CRPS, with an offline backtest based on committed public FRED snapshots.
The repository's local web application runs from v3/server.py on port 8420. Its interface includes histograms, trajectory bands, risk gauges, scenario comparisons, a domain wizard, Bayesian update controls, and standalone HTML report export. Agents can also post an inline configuration to /api/simulate, so a model does not need to create a file first.
Setup and configuration
For MCP use, install or run the package with:
The repository's baseline engine requires Python 3.8 or newer and uses only the Python standard library. The local interface can be started with:
The JSON Schema is available from GET /api/schema. Use it to validate or generate configurations containing fields such as parameters, controls, exogenous, step_logic, metrics, safety, fitness, and tunable.
Optional Rust components can accelerate metric reducers, trajectory bands, risk evaluation, histograms, and some numeric sampling. They require building the PyO3 extension with maturin; the Python implementation remains the fallback when the native module is unavailable.
Tools and capabilities
The simengine MCP server is suited to workflows that need to:
- Run repeated simulations over uncertain inputs.
- Measure probabilities, tail losses, and other configured metrics.
- Compare scenarios, control values, and input changes.
- Search tunable controls for higher fitness subject to safety bounds.
- Update distributions with supported Bayesian conjugate methods.
- Diagnose convergence and identify influential inputs.
- Generate structured results for an AI agent through the simulation API.
Expression caching is enabled for repeated expressions and for the diagnostics evaluator. Native sampling and expression paths can be disabled for benchmarking or troubleshooting through the documented environment variables.
Limitations and notes
The model author must provide valid JSON configuration, distributions, step logic, metrics, and safety or fitness definitions. The engine does not supply domain assumptions automatically; shipped examples and the template are starting points rather than a substitute for calibrated inputs.
The native acceleration path is optional and selective. Its batch sampler applies only to plain numeric variable parameters and remains disabled for correlated configurations. General expression evaluation, accumulators, and metrics continue to use Python even when the extension is installed. No hosted endpoint is available directly from the documented local setup; the README only identifies a waitlist for a hosted, no-install endpoint.