MCP Reference

Seventeen tools for your
AI assistant

The CostPad MCP server exposes your model over the Model Context Protocol. Any compliant client can read it, edit it, run pricing reviews and cost audits, and compare scenarios.

Draft schemas — parameter names and return shapes may change before the package is published.
get_simulationRead
Returns the current simulation inputs — COGS items, pricing tiers, user mix, add-ons, one-time purchases, and scalar parameters. Inspect what's loaded before running scenarios.
Parameters
section"all" | "cogs" | "tiers" | "mix" | "addOns" | "oneTimePurchases" | "scalars"Which section to return. Defaults to all. optional
Returns
cogs[]CostItemEach with name, type (fixed · per_user · per_unit), value, unitLabel, and category.
tiers[]TierName, price, units per user, color.
mix[]TierCountUser count per tier ({ tierId, count }).
addOns[] · oneTimePurchases[]object[]Add-on packs and one-time purchases.
scalarsobjectOperating params — fees, infra, churn, growth, etc.
get_economicsRead
Runs the calc engine on the current state and returns computed economics — revenue, margins, COGS, fees, free-tier impact, scale projections, and growth.
Parameters
sections[]"summary" | "tierMetrics" | "blended" | "fees" | "freeTier" | "scale" | "growth" | "addOns"Sections to include. Defaults to all. optional
Returns
summaryobjecttotalRevenue, totalCogs, grossProfit, grossMargin, totalUsers, paidUsers, freeUsers.
blendedobjectblendedARPU, blendedCOGS, blendedMargin, netRev.
feesobjectblendedFeePerSub, netRevAfterFees, marginAfterFees.
tierMetrics · freeTier · scale · growthobjectPer-tier metrics, free-tier impact, scale milestones, growth data.
get_growthRead
Month-by-month growth projection with optional parameter overrides — subscriber growth, revenue, costs, profit, and breakeven/payback months.
Parameters
monthlyChurnPctnumberMonthly churn rate (%). optional
monthlyNewSubsnumberNew subscribers per month. optional
growthRatenumberMonthly growth rate (%) for new subs. optional
monthsToProjectnumberMonths to project forward (1–120). optional
Returns
growthData[]object[]Per-month activeSubs, revenue, costs, profit, cumulativeProfit.
breakevenMonthnumberMonth the model turns cumulatively profitable.
paybackMonth · month12number · objectPayback month and the month-12 snapshot.
update_cogsWrite
Add, update, replace, or remove COGS items. Returns the updated COGS array.
Parameters
action"set" | "add" | "update" | "remove"set replaces all, add appends, update edits by id, remove deletes by id. required
items[]CostItemItems to set/add/update (not needed for remove). optional
ids[]stringIDs to delete (with action: "remove"). optional
update_tiersWrite
Add, update, replace, or remove pricing tiers. Mix entries are auto-synced when tiers change. Returns updated tiers and mix.
Parameters
action"set" | "add" | "update" | "remove"Same semantics as update_cogs. required
tiers[]TierTiers to set/add/update. optional
ids[]stringTier IDs to remove. optional
update_mixWrite
Set user counts per tier. Only listed tiers are updated; others keep their current count. Useful for pushing live subscriber counts from a billing provider.
Parameters
mix[]{ tierId, count }[]Tier-to-user-count mappings. required
run_scenarioCompute
Run a what-if by temporarily overriding any parameters — does NOT change stored state. The most powerful tool for exploring pricing changes.
Parameters
overridesobjectAny params to override (cogs, tiers, mix, addOns, fees, churn, growth…). Unspecified use current state. required
comparebooleanIf true, also return baseline + a diff. Default false. optional
Returns
economicsEconomicsScenario result when compare is false/omitted.
{ baseline, scenario, diff }objectReturned when compare is true.
export_reportCompute
Generate a formatted pricing report of the current simulation, as Markdown or JSON.
Parameters
format"markdown" | "json"Output format. Defaults to markdown. optional
sections[]"overview" | "cogs" | "tiers" | "blended" | "fees" | "freeTier" | "scale" | "growth"Sections to include. Defaults to all. optional
insightsCompute
Analyse the current model and return structured findings about pricing health — margin risks, free-tier sustainability, payment-fee drag, COGS concentration, and growth/breakeven. Read-only.
Parameters
minSeverity"info" | "warn" | "critical"Only return findings at or above this severity. Defaults to info. optional
areas[]"margin" | "freeTier" | "fees" | "cogs" | "pricing" | "growth"Restrict to specific areas. Defaults to all. optional
Returns
summaryobjectCounts by severity ({ total, critical, warn, info }).
findings[]object[]{ id, severity, area, message, suggestedAction, metric? }, sorted critical-first.
run_pricing_reviewCompute
Answer “what should I charge for <tier>?” — sweep a tier's price through the calc engine, rank by an objective, and recommend the best price that keeps the tier ladder consistent. Read-only.
Parameters
targetTierIdstringTier to price. Defaults to the highest-revenue paid tier. optional
objective"grossProfit" | "totalRevenue" | "grossMargin" | "netRevAfterFees"Metric to maximise. Defaults to grossProfit. optional
sweep{ rangePct?, steps? }± range (default 30%) and step count (default 6). optional
Returns
recommendationobjectbestPrice, changeFromCurrent, improved, rationale, deltasVsCurrent.
options[] · caveats · insightsobjectFull swept curve, ladder/churn caveats, and folded-in insights.
run_cost_auditCompute
Surface where margin leaks on the cost side: COGS by category as a share of revenue, infra cost per subscriber across scale, payment-fee drag, free-tier coverage, and a ranked leak list. Read-only.
Returns
summaryobjectgrossRevenue, totalCogs, totalFees, totalCost, grossProfit, grossMargin.
cogsByCategory[] · infraAtScaleobjectMonthly cost per category with revenue share; infra-per-sub trend across scale.
paymentFees · freeTierCoverageobjectFee drag breakdown and free-tier burn/coverage.
leaks[]object[]Cost drivers ranked by monthly $ impact, each with a suggested action.
compare_pricingCompute
Diff multiple pricing scenarios side-by-side against the current baseline. Each entry is a saved scenario name or an inline { label, overrides } object. Read-only and deterministic.
Parameters
scenarios[](string | { label?, overrides })[]1–10 scenarios to compare. Mix saved names and inline overrides. required
Returns
metrics[]object[]The compared metrics in order: { key, label, higherBetter } per metric.
columns[]object[]Baseline + one column per scenario: MRR, gross margin, gross profit, ARPU, COGS/user, net rev after fees.
bestWorstobjectBest and worst column per metric (direction-aware).
list_scenariosRead
List the named what-if scenarios saved this session, with which parameters each overrides.
Returns
countnumberHow many scenarios are saved.
scenarios[]object[]{ name, description, createdAt, overrides } — overrides is the list of overridden parameter keys.
save_scenarioWrite
Store a named what-if as an overrides bundle (same shape as run_scenario) in session state. Overwrites on duplicate name; capped at 50.
Parameters
namestringUnique scenario name. required
overridesobjectParameters this scenario overrides vs. current state. required
descriptionstringOptional human note. optional
load_scenarioWrite
Apply a saved scenario's overrides to the current state — the scenario becomes the live model. Saved scenarios are preserved.
Parameters
namestringName of a previously saved scenario. required
Returns
simulationobjectThe resulting simulation after the overrides are applied.
export_productRead
Serialize the session into a costpad.dev-importable ProductSnapshot JSON (matches the web app's product shape). Paste it into the app to load this model there.
Parameters
namestringProduct name for the snapshot. optional
brandobjectOptional brand metadata (color, type, tagline…). optional
Returns
ProductSnapshotobjectname, brand, cogs, tiers, mix, add-ons, one-time purchases, and operating scalars.
import_productWrite
Load a costpad.dev ProductSnapshot into the session (validated, 1 MB cap). Pull a model exported from the web app into the AI session.
Parameters
snapshotProductSnapshotA snapshot, e.g. the web app's export. required
Returns
simulationobjectThe loaded simulation state.
ignoredFields[]string[]Snapshot fields the MCP does not model (brand, dashboards, formatting).

Connect your assistant

Run the MCP server and point Claude, Cursor, or Windsurf at your model.

MCP server setupRead the docs