Scenariosim MCP

ScenarioSim MCP

A transparent, 100% deterministic Model Context Protocol (MCP) server that gives LLM agents a reliable what-if / scenario simulation engine.

Agents are good at describing a plan but unreliable at *projecting* it: they drift on multi-period arithmetic, mishandle compounding, and can't show their work. ScenarioSim offloads the simulation to an exact, explainable engine. You provide assumptions (growth rates, churn, pricing, costs, starting metrics, a time horizon); it returns projected outcomes over time, key metrics, the exact assumptions used, plus sensitivity analysis and break-even solving — each with a plain-language explanation.

Every number flows through decimal.js at 40-digit precision (never floats), so identical inputs always produce byte-identical output. The server is stateless — no database, no sessions, no clocks or randomness in the result.

This is the third product in a suite built to the same engineering standard as PrecisionCalc MCP (deterministic high-precision finance/business math) and DecisionMatrix MCP (transparent multi-criteria decision analysis): identical project structure, output philosophy, and Cloudflare Pages deployment.

🌐 Live hosted server (free, no install)

A public remote MCP server runs on Cloudflare's edge — point any Streamable-HTTP MCP client at it:

https://scenariosim-mcp.pages.dev/mcp

{ "mcpServers": { "scenariosim": {

"type": "http", "url": "https://scenariosim-mcp.pages.dev/mcp" } } }

It runs in open mode on the free tier (no key, 20 calls/day per IP). Paid plans (Starter $12/mo · 5,000/day, Pro $39/mo · 50,000/day) are available via Stripe Checkout — buy a plan, get an API key instantly, and send it as X-API-Key. Self-host for unlimited calls with no keys. Landing page + pricing: https://scenariosim-mcp.pages.dev.

---

What it does

Six tools, all returning a uniform, agent-parseable envelope:

Scenario templates

Every template accepts horizon (number of periods, 1–1200) and period_label (day/week/month/quarter/year, which also sets annualization). Inputs you don't provide fall back to documented defaults; unknown inputs are ignored and reported in notes. Call list_templates for the full input/output catalog.

Consistent response envelope

Every successful response contains: status, scenario, period_label, horizon, key_results (+ key_results_detail with units and full-precision value_exact), projections, assumptions_used, methodology, notes, and a natural-language explanation.

{

"status": "success", "scenario": "saas_growth", "period_label": "month", "horizon": 12, "key_results": { "ending_customers": 449.7, "ending_mrr": 26982.1, "ending_arr": 323785.2, "total_churned_customers": 82.4, "cumulative_revenue": 232104.6 }, "projections": [ { "period": 0, "customers": 200, "mrr": 12000, "new_customers": 0, "churned_customers": 0 }, { "period": 1, "customers": 234, "mrr": 14040, "new_customers": 40, "churned_customers": 6 } ], "assumptions_used": { "template": "saas_growth", "starting_customers": "200", "new_customers_per_period": "40", "acquisition_growth_rate": "0", "churn_rate": "0.03", "arpu": "60", "horizon": 12, "period_label": "month" }, "methodology": { "model": "SaaS Growth", "primary_output": "ending_mrr", "precision": "decimal.js (40 significant digits)", "deterministic": true, "period_convention": "Period 0 is the starting state; periods 1..12 are projected. 12 month(s) per year." }, "notes": ["Churn is applied to the prior period's base before new customers are added."], "explanation": "Starting from 200 customers and adding 40 per month (churn 3%), after 12 months you reach ..." }

Errors never cross the tool boundary as exceptions — they come back as a structured, actionable envelope:

{

"status": "error", "error": { "type": "unknown_template", "message": "Unknown scenario template 'saaas'.", "hint": "Available templates: saas_growth, pricing_change, churn_impact, cost_reduction, hiring_plan, cash_runway, unit_economics, marketing_funnel, compound_growth. Call list_templates for details ..." } }

Design note — exact numbers: headline numbers in key_results are

deterministically rounded (6 dp) for easy consumption; key_results_detail[].value_exact

and assumptions_used carry full-precision strings so no precision is lost in JSON.

All internal math is exact 40-digit decimal.

---

Project structure

scenariosim-mcp/

├── worker-src/ │ ├── index.mjs # Cloudflare Pages Function (_worker.js): MCP over Streamable HTTP + billing routes │ ├── engine.mjs # The deterministic simulation engine: 9 templates + 6 tools + solver + validation │ └── billing.mjs # Stripe Checkout + KV-backed API keys, quota metering, webhook ├── server.mjs # Local stdio MCP server (same engine, no network/state) ├── site/ │ ├── index.html # Static landing / pricing / docs page │ ├── mcp.json # Machine-readable connection manifest │ ├── llms.txt # LLM-friendly summary │ └── _worker.js # Built bundle (esbuild output; git-ignored) ├── tests/ │ └── engine.test.mjs # 29 core simulation-logic tests (node --test) ├── examples/ │ └── agent_example.mjs # End-to-end MCP client demo over HTTP ├── package.json # build / deploy / dev / test scripts ├── wrangler.toml # Cloudflare Pages config ├── .env.example # Optional auth/rate-limit env reference ├── LICENSE # MIT └── README.md

Separation of concerns: engine.mjs is pure and transport-agnostic (import it directly in tests or any Node/Deno/edge runtime); index.mjs only handles the MCP JSON-RPC wiring, HTTP, CORS, and the auth/metering seam; server.mjs re-uses the same engine over stdio.

---

Requirements

• Node 18+ (for the build, tests, and local dev). Only two dev/runtime deps: decimal.js (math) and esbuild (bundler).
• A Cloudflare account (free tier is fine) to deploy the hosted version.

---

Run it locally

git clone <your-fork> scenariosim-mcp && cd scenariosim-mcp

npm install

Run the test suite (no server needed)

npm test

Serve the MCP endpoint locally via Wrangler (builds + runs Pages dev)

npm run dev # -> http://127.0.0.1:8788/mcp

Try the end-to-end client demo (hosted by default, or pass a local URL)

node examples/agent_example.mjs node examples/agent_example.mjs http://127.0.0.1:8788

Or run the dependency-light stdio server directly

node server.mjs

Quick manual call:

curl -s http://127.0.0.1:8788/mcp \

-H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{ "name":"list_templates","arguments":{}}}'

---

Install via npm (stdio, no hosting)

Run the server locally over stdio with a single command — nothing to deploy:

npx -y scenariosim-mcp

Claude Desktop / any stdio MCP client (claude_desktop_config.json):

{ "mcpServers": { "scenariosim": { "command": "npx", "args": ["-y", "scenariosim-mcp"] } } }

This is the same deterministic engine as the hosted server, running on your machine.

Client configuration

Cursor — ~/.cursor/mcp.json

{ "mcpServers": { "scenariosim": {

"url": "https://scenariosim-mcp.pages.dev/mcp" } } }

Claude Desktop — claude_desktop_config.json

Claude Desktop launches stdio servers, so bridge to the HTTP endpoint with mcp-remote:

{ "mcpServers": { "scenariosim": {

"command": "npx", "args": ["-y", "mcp-remote", "https://scenariosim-mcp.pages.dev/mcp"] } } }

VS Code — .vscode/mcp.json

{ "servers": { "scenariosim": {

"type": "http", "url": "https://scenariosim-mcp.pages.dev/mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json

{ "mcpServers": { "scenariosim": {

"serverUrl": "https://scenariosim-mcp.pages.dev/mcp" } } }

Any Streamable-HTTP MCP client

Point it at https://scenariosim-mcp.pages.dev/mcp (or your self-hosted URL). If you enable auth, add X-API-Key (or Authorization: Bearer ) in the client's headers.

---

Tools & parameters

run_scenario(template?, inputs?, metrics?, horizon?, period_label?)

• template — one of the template ids above (aliases like saas, pricing, runway, ltv, funnel also resolve). Omit it (or pass "custom") to run a free-form model.
• inputs — the assumptions object for the template, e.g. { "churn_rate": 0.03, "arpu": 60 }. Also accepted as assumptions, or spread at the top level. Missing keys use documented defaults.
• metrics — *(custom mode)* array of { name, start, growth_rate?, mode? } where mode is "compound" (default, x·(1+r)ⁿ) or "linear" (x·(1+r·n)).
• horizon — number of periods to project (1–1200). Default per template (usually 12).
• period_label — day/week/month/quarter/year (default month).

sensitivity_analysis(template, variable|variables, target_metric?, variation?, steps?, values?, min?, max?, inputs?, horizon?)

Sweeps each listed input across a range (default ±variation=0.2 around the baseline, steps=5) while all others stay at baseline, recomputing target_metric (defaults to the template's primary output) at each point. Returns per-variable sweep rows, an elasticity_estimate, the output_range, and a most_influential ranking. You can also give explicit values: [...] or a min/max grid instead of variation.

break_even(template, solve_for, target_metric?, target_value, bounds?, inputs?, horizon?)

Solves for the value of solve_for (an input name) that makes target_metric equal target_value, via deterministic bisection with automatic bracket expans