Use WaterfallBridge with AI Agents (MCP)

An AI-callable KPI bridge analysis engine.

Your users don't want to learn a workflow — they just want to ask a question. WaterfallBridge exposes an MCP server so an AI agent can open the app, prepare the data, run the bridge, read the result and explain the drivers, all from one plain-language sentence. The math is always the deterministic WaterfallBridge engine; the AI is only the operator.

How Claude, Cursor, Codex and ChatGPT call it

Install the WaterfallBridge AI Agent (a small Windows app). In the installer, tick the AI tools you use — it registers an MCP server named waterfall-bridge for you, with no JSON editing.
Restart your AI tool. You'll see waterfall-bridge listed as a tool source (e.g. in Cursor under Settings → MCP).
Sign in once from the chat, then point the agent at a file and ask your question.

You → any MCP client
"Use waterfall-bridge to analyze D:\Data\sales-2024.xlsx and tell me why 2024 Q4 margin % dropped versus 2023 Q1, broken down by product."

The full step-by-step setup for each tool — including the in-app "Ask AI" panel — is in the AI Assistant guide. New here? Jump to Install: two ways.

Install: two ways

Both options expose the exact same waterfall-bridge tools — they only differ in how the server is packaged. Pick whichever fits you.

① AI Agent installer · Windows

Easiest · no Node needed · bundles its own browser

One .exe download. In the installer, tick the AI tools you use — it writes the Cursor / Claude / Codex config for you (no JSON or TOML editing).
Ships a system tray and a standalone "Ask AI" window; Chromium is bundled, so nothing else to install.
Best for non-developers and Windows users.

⬇ Download AI Agent (Windows)

② npm package · macOS / Windows / Linux

For developers · cross-platform · no installer

Requires Node.js 18+. On first run it downloads a Chromium build (~150 MB, one time).
Add one block to your AI tool's MCP config (snippets below). Nothing is installed globally — npx fetches it on demand.
Published as @waterfallbridge/mcp and listed on the official MCP Registry.

npx -y @waterfallbridge/mcp --mode=stdio

Config snippets for the npm method

Cursor — ~/.cursor/mcp.json (or project .cursor/mcp.json)

{
  "mcpServers": {
    "waterfall-bridge": {
      "command": "npx",
      "args": ["-y", "@waterfallbridge/mcp", "--mode=stdio"],
      "env": { "WB_HEADLESS": "false" }
    }
  }
}

Claude Desktop — claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "waterfall-bridge": {
      "command": "npx",
      "args": ["-y", "@waterfallbridge/mcp", "--mode=stdio"],
      "env": { "WB_HEADLESS": "false" }
    }
  }
}

Codex CLI — ~/.codex/config.toml

[mcp_servers.waterfall-bridge]
command = "npx"
args = ["-y", "@waterfallbridge/mcp", "--mode=stdio"]
env = { WB_HEADLESS = "false" }

After saving, restart the AI tool — you'll see waterfall-bridge in its MCP list. Sign in once from the chat, then point the agent at a file and ask your question. A WaterfallBridge account with an active subscription is required for full analysis.

Inputs and outputs

Supported inputs

CSV files
Excel files (.xlsx / .xlsm)
Dimension — what to break the change down by
Key — the contribution-analysis breakdown
Result — the KPI you want explained
SumY — numerator for rate metrics
SumN — denominator for rate metrics

Returned outputs

Bridge / chart table (baseline → comparison)
Driver contribution analysis by key
Added data and removed data rows
Plain-language root-cause insight
Optional Excel / report export (on request)

The MCP tool surface

The waterfall-bridge server exposes a focused set of tools that an agent chains together:

open_app  →  check_data_preparation  →  suggest_bridge_schema  →  prepare_bridge_xlsx
        →  upload_file  →  run_bridge  →  set_baseline / set_comparison  →  run_analysis
        →  get_chart_data + get_contribution_table + get_insights  →  export (optional)

Tool	What it does
open_app	Starts the WaterfallBridge engine session.
check_data_preparation	Validates the file is a flat, one-row-per-record table and lists fixes if not.
suggest_bridge_schema	Proposes the Dimension / Key / Result / SumY / SumN mapping for confirmation.
run_bridge / run_analysis	Runs the deterministic bridge math on the baseline and comparison.
get_chart_data / get_contribution_table / get_insights	Returns the bridge, the driver contribution by key, and a root-cause narrative.
export_xlsx / export_report	Produces a deliverable file — only when you ask.

Security & data handling

No user data is stored on our servers. Your file is processed locally and only lightweight algorithm requests reach the server to run the bridge math. The deterministic, closed-form algorithm runs through your account; the AI never invents numbers. Your login session and AI keys stay encrypted on your machine, and the agent can only read folders you approve (by default Downloads, Desktop and Documents).

Account required. Full analysis needs a WaterfallBridge account with an active subscription. You can try the free demo first. The one-click AI Agent installer is Windows-only; on macOS and Linux use the cross-platform npm package (Node.js 18+).

Frequently asked questions

How do I call WaterfallBridge from Claude, Cursor, Codex or ChatGPT?

Two ways. (1) Install the WaterfallBridge AI Agent on Windows and tick the AI tools you use — the installer registers an MCP server named waterfall-bridge for you. (2) Or, if you have Node.js, add the @waterfallbridge/mcp npm package to your tool's MCP config (npx -y @waterfallbridge/mcp --mode=stdio) — see Install: two ways. Then restart the AI tool and ask in plain language, e.g. "Use waterfall-bridge to analyze sales-2024.xlsx and explain why Q4 margin dropped versus Q1."

What inputs does the WaterfallBridge MCP server accept?

It accepts CSV and Excel (.xlsx/.xlsm) files. You configure the bridge schema with Dimension, Key, Result, SumY (numerator) and SumN (denominator). The agent can suggest the schema automatically and ask you to confirm.

What outputs does WaterfallBridge return to the AI agent?

It returns a bridge / chart table, a driver contribution analysis broken down by the chosen key, added and removed data rows, and a plain-language root-cause insight. The agent uses these to write the explanation.

Is user data stored on the server and does the algorithm run on the server?

No user data is stored on WaterfallBridge servers. Files are processed locally; only lightweight algorithm requests reach the server to run the deterministic bridge math. Login sessions and AI keys stay encrypted on your machine. A WaterfallBridge account with an active subscription is required for full analysis.

Use WaterfallBridge with AI Agents