Documentation for FiceCal + MCP

Quick start

1. In Quick actions, follow the first-timer strip: Step 1: Pick your role (Finance, Operations, Architecture, Executive).
2. Use the Start Step 2 button to jump directly to the required core fields: Total Infra Cost and Revenue / Client (ARPU).
3. After Step 2 is complete, Step 3 unlocks your role-specific top 3 outcomes + first action. Use this as your immediate readout before deeper tuning.
4. Then use Group B controls for model tuning and Quantify Business Value inputs: CUD, target margin, budget, forecast assumptions, savings realization, and cost avoidance.
5. Optionally add multi-technology costs (SaaS, licensing, private cloud, data center, labor) and scope domains for normalization.
6. Review Group C auto-calculated outputs and Group E health/recommendation cards, then use the chart section to inspect cost/revenue/profit behavior across scale.
7. Use all 4 scenario demos (Healthy, Unhealthy, Reliability Healthy, Reliability Unhealthy) to validate expected KPI behavior before entering live portfolio assumptions.
8. For resilience planning, enable Reliability Economics and compare reliability-adjusted profit, ARPU uplift needed, and extra clients needed at current ARPU.

Calculator sections explained

How calculations work

The calculator uses deterministic formulas and scan-based thresholds to turn your inputs into decision-ready outputs for viability, pricing, growth planning, and reliability trade-off analysis.

Quantify Business Value extension formulas

• ForecastClients = n * (1 + growth%)
• BaselineMargin = ForecastRevenue - ForecastCost
• BestMargin = ForecastRevenue - (ForecastCost * (1 - efficiency%))
• WorstMargin = ForecastRevenue - (ForecastCost * (1 + drift%))
• ForecastSpread = BestMargin - WorstMargin
• TotalRealizedValue = RealizedSavings + CostAvoidance
• RealizationRatio = TotalRealizedValue / IdentifiedSavings
• ResidualValueGap = IdentifiedSavings - TotalRealizedValue

Glossary and definitions

This glossary is consolidated here to keep public documentation in one place and avoid cross-page fragmentation.

How to use the calculator effectively

Recommended workflow

1. Select the role that matches your decision context. This automatically aligns recommendation emphasis and guided-path framing.
2. Complete only the two core fields first (Infra Cost + ARPU) to unlock the role preview and avoid early input overload.
3. Review "You'll get first" outcomes and "Do this next" before touching advanced controls.
4. Set a conservative CUD percentage first, then refine after observing sensitivity.
5. Set monthly budget and check Budget Variance to identify immediate overrun/headroom posture.
6. Add forecast growth, best-case efficiency, and worst-case drift to activate the forecast margin/confidence band outputs.
7. Turn on Reliability Economics when incident and SLA posture matters; review reliability-adjusted profit, ARPU uplift, and extra-clients implications before approving scale plans.
8. Add identified savings, realized savings, and cost avoidance to track realization ratio and residual value gap.
9. Use output tooltips to validate assumptions behind each metric, then cross-check with chart curves for where margins compress at higher client counts.
10. Use health recommendations with category filters to prioritize short-term vs strategic actions.

Scenario comparison approach

• Scenario A (Healthy): baseline viability and balanced efficiency posture.
• Scenario B (Unhealthy): downside stress posture with weak margin/efficiency signals.
• Scenario C (Reliability Healthy): resilience investment and low breach-risk reliability state.
• Scenario D (Reliability Unhealthy): elevated outage/breach pressure and downside-heavy reliability state.
• Compare break-even, CCER, contribution margin, reliability-adjusted profit, ARPU uplift needed, and extra-clients-needed across scenarios to align finance and operations decisions.

Health zone and recommendations

The Health section continuously evaluates your model posture and labels it as a zone with an associated score and guidance.

• Signals include break-even behavior, efficiency posture (CCER), margin quality, and commitment coverage.
• Recommendation cards are prioritized to guide near-term and medium-term FinOps actions.
• Category filters (All, Infrastructure, Pricing, Marketing, CRM, Governance) let users focus on a specific execution lane.
• No-break-even conditions now surface strategic guidance beyond pure infra optimization (pricing floor adjustment, funnel acceleration, and CRM retention/expansion actions).
• Provider filters help tailor actions to cloud-specific optimization opportunities.

Share-state links

The calculator can generate a URL that captures the current model state so colleagues can open the same assumptions without re-entering inputs, preserving analysis context for review meetings and handoffs.

• Includes all active numeric inputs, selected tech domains, selected providers, and curve visibility toggles.
• This now includes Quantify Business Value controls (budget, forecast assumptions, savings realization, cost avoidance).
• Also includes AI token economics settings (pricing mode, rates, volumes, retry/premium mix, overhead, allocation policy).
• Also includes reliability economics settings (SLO/SLI assumptions, incident economics, and reliability investment).
• Includes all curve toggles, including reliability overlays (total-rel, profit-rel) when enabled.
• Also includes UI context: selected role (ui) and interface mode (um) so shared links reopen in the same decision lens.
• The URL contains an encoded ?state= token.
• On load, the app decodes and validates this state, then recalculates outputs, chart, health, and recommendations.

MCP overview

The same FiceCal model is available through a Model Context Protocol server so AI assistants can call the model directly in workflows, audits, and planning automations.

• Transport: JSON-RPC over stdio in the current implementation.
• Core logic is shared between browser model behavior and MCP tool handlers for unit economics, reliability economics, health scoring, recommendation prioritization, and state encoding/decoding.
• finops.calculate supports multi-technology scope through techDomains and optional non-cloud monthly cost inputs, plus reliability inputs/outputs for SLA/SLO/SLI parity.
• MCP v0.3.0 keeps share-state parity with the calculator by supporting UI role/mode context (uiIntent, uiMode) in generated state tokens.
• finops.recommend supports category-aware filtering and can include strategic pricing/marketing/CRM recommendations when inputs are supplied.
• Useful for repeatable analysis, not just manual UI interactions.

MCP tools and contracts

MCP setup and usage

Local setup

1. Clone finops-calculator or finops-calculator-mcp.
2. Install dependencies in the MCP workspace.
3. Run tests to verify contract/protocol behavior.
4. Run parity tests to verify that share-state constants, reliability fixtures, and UI option values have not drifted from index.html.
5. Register MCP server command in your client config.

# Example command path for MCP client config
node /absolute/path/to/mcp/server/index.js

Client connection references

Use the MCP connection examples from the finops-calculator-mcp repository (for example, github.com/duksh/finops-calculator-mcp) for Cursor, Windsurf, and Claude Desktop integration.

Example MCP request/response shape

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "finops.calculate",
    "arguments": {
      "inputs": {
        "nRef": 120,
        "devPerClient": 500,
        "infraTotal": 2400,
        "techDomains": ["cloud", "saas"],
        "costSaaS": 600,
        "reliabilityEnabled": "on",
        "sloTargetAvailabilityPct": 99.9,
        "sliObservedAvailabilityPct": 99.7,
        "incidentCountMonthly": 3,
        "mttrHours": 1.2,
        "incidentBlendedHourlyRate": 100,
        "criticalRevenuePerMinute": 25,
        "arrExposedMonthly": 70000,
        "slaPenaltyRatePerBreachPointMonthly": 3500,
        "reliabilityInvestmentMonthly": 1500,
        "startupTargetPrice": 35,
        "cudPct": 30,
        "margin": 15,
        "nMax": 2000
      },
      "providers": ["aws"],
      "uiIntent": "operations",
      "uiMode": "operator",
      "options": {
        "includeHealth": true,
        "includeRecommendations": true,
        "includeStateToken": true
      }
    }
  }
}

Decode state token and restore UI context

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "finops.state.decode",
    "arguments": {
      "stateToken": "..."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "state": {
      "v": 1,
      "ui": "operations",
      "um": "operator",
      "i": { "infraTotal": "2400", "ARPU": "30" },
      "td": ["cloud", "saas"],
      "p": ["aws"],
      "h": []
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "outputs": {
      "breakEvenClients": 51,
      "minPricePerClient": 27.79,
      "reliability": {
        "expectedReliabilityFailureCostMonthly": 10887.5,
        "reliabilityAdjustedCostMonthly": 15487.5,
        "reliabilityRiskBand": "medium",
        "reliabilityDataConfidence": "high"
      },
      "normalization": {
        "selectedDomains": ["cloud", "saas"],
        "coveragePct": 100,
        "normalizedTechCostPerClient": 25,
        "confidence": "High"
      }
    },
    "health": {
      "zoneKey": "yellow",
      "zoneTitle": "Yellow Zone - Needs Improvement",
      "score": 72
    },
    "recommendations": [
      {
        "title": "CCER below 3x",
        "category": "governance",
        "priority": "high"
      }
    ],
    "stateToken": "..."
  }
}

Recommendation tool with category filter

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "finops.recommend",
    "arguments": {
      "zoneKey": "red",
      "providers": ["aws"],
      "category": "marketing",
      "inputs": {
        "nRef": 80,
        "infraTotal": 2400,
        "startupTargetPrice": 35
      }
    }
  }
}

Troubleshooting

Calculator page issues

• Unexpected output values: verify units (monthly costs, not annual).
• Chart looks flat: increase chart scale or adjust ARPU/cost assumptions.
• Budget Variance remains blank: provide both modeled cost inputs and a positive monthly budget.
• Forecast band is missing: add ARPU (or startup-derived ARPU) and at least one forecast assumption.
• Realization ratio is missing: identified savings must be greater than zero to compute ratio/gap.
• Shared link does not restore: ensure full URL including ?state= is copied.
• Role/mode not matching after opening link: regenerate the link after selecting role and mode so ui/um are captured.

MCP issues

• Tools not visible: confirm server command path and restart the MCP client.
• Tool call errors: validate argument types against the schema definitions in the finops-calculator-mcp repository.
• Reliability outputs are blank: set reliabilityEnabled to on and provide at least SLO/SLI baseline assumptions.
• Unexpected decode errors: ensure the token is complete and unmodified.
• MCP parity failures: run npm run test:parity in finops-calculator-mcp/server and inspect drift in share-state version or UI option constants.