Tools

The CostPad MCP server (costpad) exposes 23 tools. Twelve read & analyze the model and run scenarios; eleven modify the in-memory state.

Common shapes

Several tools share these object shapes:

• COGS item — { id?, name, type: "fixed" | "per_user" | "per_unit", value, unitLabel?, category?: "infra" | "api" | "tooling" | "support" | "other" }
• Tier — { id?, name, price, unitsPerUser, color? }
• Mix entry — { tierId, count }
• Add-on pack — { id?, name, price, cogs }
• One-time purchase — { id?, name, price, cogs, attachRate (0–100) }

Read & analyze

These run on the current model without changing it. All are available in --read-only mode.

get_simulation

Returns the current simulation inputs (COGS, tiers, mix, add-ons, scalars). Use it to see what's loaded before running scenarios.

• section — one of all, cogs, tiers, mix, addOns, oneTimePurchases, scalars. Default all.

get_economics

Runs the calc engine on the current state and returns computed economics — revenue, margins, COGS, fees, scale projections, and growth.

• sections — subset of summary, tierMetrics, blended, fees, freeTier, scale, growth, addOns. Default: all.

insights

Structured findings about pricing health — margin risks, free-tier sustainability, payment-fee drag, COGS concentration, and growth/breakeven. Read-only analysis.

• minSeverity — info | warn | critical.
• areas — subset of margin, freeTier, fees, cogs, pricing, growth.

run_pricing_review

Answers "what should I charge for a tier?" — sweeps a target tier's price, ranks results by an objective, and returns a recommended price with before/after deltas, caveats, and folded-in insights.

• targetTierId — the tier to sweep.
• objective — grossProfit | totalRevenue | grossMargin | netRevAfterFees.
• sweep — { rangePct (1–90), steps (2–25) }.

run_cost_audit

Surfaces where margin leaks on the cost side: COGS by category as a share of revenue, infra cost per subscriber across scale, fee drag, free-tier coverage, and a ranked leak list with suggested actions. No parameters.

compare_pricing

Diffs multiple pricing scenarios side-by-side against the current baseline, marking best/worst per metric (MRR, gross margin, gross profit, blended ARPU, COGS/user, net revenue after fees).

• scenarios — 1–10 entries, each a saved scenario name or an inline { label, overrides }.

export_product

Serializes the session into a costpad.dev-importable ProductSnapshot JSON you can paste into the web app. No parameters.

list_scenarios

Lists the named what-if scenarios saved this session and which parameters each overrides. No parameters.

run_scenario

Runs a what-if by temporarily overriding any parameters — does not change stored state. The most flexible way to explore changes before committing them.

• any model parameters as overrides.
• compare — when true, returns both baseline and scenario results with a diff of key metrics.

get_growth

Month-by-month growth projections: subscriber growth, revenue, costs, profit, and breakeven/payback months.

• monthlyChurnPct, monthlyNewSubs, growthRate, monthsToProject — optional overrides (default: current state).

export_report

Generates a formatted pricing report of the current simulation.

• format — markdown | json. Default markdown.
• sections — subset of overview, cogs, tiers, blended, fees, freeTier, scale, growth. Default: all.

bridge_status

Reports whether a local CostPad Desktop is attached over the bridge (connected / offline), its version, and last sync time — so an assistant knows whether it can push or pull. See Desktop bridge.

Modify state

These change the in-memory model. None are available in --read-only mode.

update_cogs

Add, update, replace, or remove COGS items; returns the updated COGS array.

• action — set (replace all) | add | update (by id) | remove.
• items — COGS items for set/add/update. ids — ids for remove.

update_tiers

Add, update, replace, or remove pricing tiers. Mix entries auto-sync when tiers change.

• action — set | add | update | remove.
• tiers — tier objects. ids — ids for remove.

update_mix

Sets user counts per tier. Only listed tiers are updated; others keep their current count.

• mix entries { tierId, count }.

save_scenario

Stores a named what-if as an overrides bundle in session state (same shape as run_scenario) so it can be revisited, loaded, or compared. Re-saving a name overwrites it.

load_scenario

Applies a saved scenario's overrides to the live state — the scenario becomes the current model. To compare without changing state, use compare_pricing or run_scenario instead.

update_addons

Add, update, replace, or remove add-on packs (top-up / upsell). Same action shape as update_cogs; returns the updated add-ons array. Add-on economics feed get_economics (pack margins, blended COGS).

• action — set | add | update | remove.
• items — add-on packs. ids — ids for remove.

update_one_time_purchases

Add, update, replace, or remove one-time purchases (e.g. setup or onboarding fees). attachRate is the percent of paid subscribers who buy (0–100); blended ARPU reflects the change.

• action — set | add | update | remove.
• items — one-time purchases. ids — ids for remove.

import_product

Loads a costpad.dev ProductSnapshot into the session (validated). Model fields (cogs/tiers/mix/add-ons/one-time purchases/scalars) are loaded; presentation and dashboard fields are ignored and reported.

reset_state

Reinitializes the session to the built-in defaults — clears COGS, tiers, mix, add-ons, one-time purchases, scalars, and saved scenarios. No parameters.

load_preset

Loads a named sample dataset into the session, replacing the current simulation (saved scenarios are cleared).

• name — b2b-saas | usage-based-api. See Presets and configuration.

pull_from_desktop

Pulls the connected CostPad Desktop's current product into the session, replacing the simulation, so analysis starts from the user's real numbers. Errors clearly when no Desktop is attached. See Desktop bridge.

Tool metadata

Every tool carries annotations so hosts can decide auto-approve vs. confirm: read & analyze tools are readOnlyHint: true; modify tools are readOnlyHint: false, with destructiveHint: true on replace-style tools. openWorldHint is false everywhere — all state is local and in-memory.

The data tools (get_simulation, get_economics, insights, run_pricing_review, run_cost_audit, compare_pricing, get_growth, export_product) also return structured output: a structuredContent object matching a declared outputSchema, so hosts can validate and render results alongside the text.