Product

RECOMMENDED

FREE TRIAL

Resources

Baremetrics MCP: A New Playground and 13 New Tools (48 in Total)

By Luke Marshall on November 18, 2026
Last updated on November 18, 2026

The Baremetrics MCP now has a playground and 13 new tools. The MCP Playground, in Settings → Integrations → MCP, lets you browse the tool catalog, run any tool on your own account’s data and read the result before you connect an AI assistant. The 13 new tools add growth, retention and customer analysis, bringing the catalog to 48 read-only tools: 18 original API tools and 30 RevOS tools.

Why it matters: the new tools return calculated rates, denominators, amounts and totals, which reduces the arithmetic an assistant has to reconstruct from raw records. Each one has documented limits: which population it covers, how far back it can look and, for some tools, when it refuses a question instead of giving a partial answer.

This guide is for SaaS founders, RevOps and data people, and developers. It covers the playground, how to connect an assistant, all 13 tools with their limits, four multi-tool workflows, the improvements to existing tools and the design principles behind them. If you’re new to the Baremetrics MCP, start with the setup section.

What shipped
MCP PlaygroundSettings → Integrations → MCP: browse every tool, run it with an account-aware prefilled example, read formatted results, open the methodology notes or raw MCP response
New tools13 tools for growth quality, existing-customer retention, customer journeys, revenue dependence and exposure, stability and scenarios
Catalog48 tools in total: 18 original API tools and 30 RevOS tools
AccessRead-only. No tool changes anything in the account
Existing toolsComplete plan rankings and segment discovery, exact cohort totals, calculated-date boundaries and corrected results

What is the Baremetrics MCP Playground?

The MCP Playground brings the tool catalog into the Baremetrics app. You no longer need to set up an AI client or construct an API request just to discover what the MCP can do. You can browse the tools, try them on your account’s data and understand the results first.

How to run a tool in the playground

  1. Open Settings → Integrations → MCP.
  2. Pick a tool from the full list on the left.
  3. Use the prefilled example. Required inputs use the account’s calculated dates and real records where available, and optional fields include examples too.
  4. Click Run tool. Review the formatted figures, tables and supported charts. Open the methodology notes or the raw MCP response when you need more detail.
  5. Adjust the inputs to explore another period, customer, segment or question. Switching tools keeps the page and list in place.

If an account is missing a required record or enough calculated history, the playground explains what is missing instead of inserting a fake ID.

Results you can read

The playground leads with the answer. Money and percentages use the same formatting as the product. Scalar results appear as labeled values, and tabular results use readable column labels.

The detail is still there when you need it. Each result has two panels:

  • How to read this result: the detailed limitations and methodology notes for that tool.
  • Raw response: the unchanged MCP response.

For example, Revenue Exposure shows scored MRR, exposed MRR, heuristic loss, customer count and exposed share together. The short interpretation note stays visible next to them: exposure is not confirmed loss, and heuristic loss is not a forecast.

Baremetrics MCP

Ask your AI tool about your revenue data

Get the setup snippet for Claude Code, Cursor, Claude Desktop or Codex, plus prompts to try on your own Baremetrics data. It works on a free trial too.

Set up Baremetrics MCP →

How do you connect an AI assistant to the Baremetrics MCP?

When you’re ready, click Connect your assistant in the playground. It opens the setup instructions, the server URL and a Claude Code example, and links to baremetrics.com/mcp for client-specific installation guidance.

You can use any compatible MCP client, subject to that client’s authentication support. Today that means desktop clients. Web-based clients such as ChatGPT and Claude.ai in the browser aren’t supported yet: they connect over OAuth, and the Baremetrics MCP server currently uses header-based authentication.

What you need:

  • A Baremetrics account (trial or paid).
  • Your Baremetrics API key, from Settings → API. Live keys start with lk_.
  • A supported AI tool: Claude Desktop, Claude Code, Cursor or Codex.

The server URL is https://app.baremetrics.com/mcp. In every snippet below, replace <BM_API_KEY> with your live API key. The full instructions are in the MCP setup guide in the help center.

Claude Code

Run this in your terminal and the configuration entry is added for you:

claude mcp add baremetrics https://app.baremetrics.com/mcp \
  --transport http \
  --scope user \
  --header "Authorization: Bearer <BM_API_KEY>"

Cursor

Add the entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "baremetrics": {
      "url": "https://app.baremetrics.com/mcp",
      "headers": {
        "Authorization": "Bearer <BM_API_KEY>"
      }
    }
  }
}

Claude Desktop

Open claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) and add the entry alongside your existing configuration:

{
  "mcpServers": {
    "baremetrics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.baremetrics.com/mcp",
        "--header",
        "Authorization: Bearer <BM_API_KEY>"
      ]
    }
  }
}

Codex

Add this to ~/.codex/config.toml, then set the BM_API_KEY environment variable in your shell:

[mcp_servers.baremetrics]
url = "https://app.baremetrics.com/mcp"
bearer_token_env_var = "BM_API_KEY"

Other clients (STDIO)

For AI tools that only support MCP over STDIO, not HTTP, use mcp-remote as a proxy (it requires Node.js). The generalized JSON config is the same as the Claude Desktop entry above. Consult your client’s documentation for exact file paths and formats.

A note on mcp-remote: the Claude Desktop and STDIO setups mean trusting mcp-remote with your API key. It is an open-source tool that bridges the gap for clients without native HTTP transport. Review it at github.com/geelen/mcp-remote before you use it.

Already connected? Reconnect the connector or restart your assistant to refresh tool discovery, so it picks up the new tools.

The 13 new MCP tools at a glance

The 13 additions answer questions about growth quality, existing-customer retention, customer journeys, revenue dependence and exposure, and stability and scenarios. The sections after this table cover each tool in detail.

ToolQuestion it answersKey limits
acquisition_outcomesDo newer acquisition groups retain better at the same age?Up to 1 year of acquisition dates; mature customers only; observational
retention_cohortsCustomer and revenue retention curves by cohort ageUp to 12 acquisition months; ages 0–24; missing checkpoints are null
trial_cohortsWhich trials convert and keep paying?Up to 1 year of trial starts; episodes, not unique customers
discount_outcomesWhat happens to discounted customers?Up to 5 years; no segments; not causal
retention_bridgeHow much opening MRR remained?Up to 5 years; new customers excluded; 50 largest changes shown
customer_breakdownRetention by customer size, tenure, interval, subscription count or countryUp to 5 years; disjoint groups with an exact total
lifecycle_timingWhen do churn and upgrades happen by tenure?Up to 1 year; event-age shares are not churn rates
plan_transitionsWhich plans do customers move between?Up to 1 year; top pairs plus “other” and an exact total
revenue_concentrationHow dependent is MRR on the top customers?No segments; top sets overlap; 50-row customer view
revenue_exposureHow much MRR does the current risk classification flag?Current health features only; exposure is not confirmed loss
series_statsHow stable is a metric, and which segments vary most?3–36 whole months; partial periods dropped
population_compareHow does a metric compare across 2–4 saved segments?Up to 1 year; segments can overlap, so never add rows together
growth_scenariosWhat happens to MRR under explicit assumptions?1–24 months; a scenario, not a forecast

The example prompts below are prompts to try, not claims about any account’s results.

Growth quality: acquisition, cohort, trial and discount tools

These four tools ask whether newer growth is better growth: do newer customer cohorts retain better at the same age, which trials convert and keep paying, and what happens to discounted customers?

acquisition_outcomes

What it returns: Compares new paying customers at the same age, grouped by acquisition month, initial billing interval or initial discount bucket. Checkpoint results cover paid retention, revenue retention and ARPU, and the output includes total: true rows calculated from combined denominators.

Example prompt: For customers acquired January–June 2026, compare monthly vs annual billing at age 3 months: paid retention, revenue retention and ARPU.

Limits and how to read them:

  • Up to 1 year of acquisition dates; age 1–24 months.
  • Only mature customers enter checkpoint rates. A new cohort with no rate yet has an incomplete observation window: use the mature count and missing-checkpoint information, and don’t treat missing as zero.
  • Observational. It reports observed outcomes, not causal effects, and has no marketing-channel attribution.
  • Groupings use metadata at acquisition; historical plan metadata is not versioned.
  • Don’t average cohort rates. Use the total rows.

retention_cohorts

What it returns: Customer and revenue retention at one or several ages, using the published cohort snapshot, with an optional pooled retention curve. Read it alongside our guide to cohort analysis.

Example prompt: Show the January–March 2026 cohorts at ages 0, 1, 3 and 6 months. Also show one pooled retention curve.

Limits and how to read them:

  • Up to 12 acquisition months; ages 0–24, up to 13 ages and 48 cohort/age rows.
  • Missing checkpoints are null, not zero.
  • Revenue retention includes expansion.
  • Retention-cohort totals require every selected cohort to have reached the requested age.

trial_cohorts

What it returns: Follows subscription trial episodes through conversion, paid retention, revenue retention and expansion. Group by month, plan, configured trial length or billing interval. Useful next to the trial conversion rate you already track.

Example prompt: For trials started January–June 2026, compare configured trial lengths: conversion within 30 days, paid retention 90 days after conversion, and expansion.

Limits and how to read them:

  • Up to 1 year of trial starts; conversion window 1–90 days; retention checkpoint 1–365 days.
  • Mature episodes only in the relevant rates.
  • Counts subscription episodes, not unique customers.
  • No LTV or causal conclusions.

discount_outcomes

What it returns: Follows fixed opening-date discount buckets through retention, MRR and return to full price.

Example prompt: Compare full-price and discounted customers from January 1 to October 31: who retained, churned or returned to full price?

Limits and how to read them:

  • Up to 5 years; the end date must be after the start date.
  • No segments.
  • Observational, not causal, and not matched by tenure. It doesn’t show that a discount caused an outcome.
  • The customer view shows up to 50 opening discounts.

Existing-customer retention: retention_bridge and customer_breakdown

Of the customers paying at the start of the year, how much MRR remained, and how does retention differ by customer size or tenure? Both tools start from a fixed opening population and exclude new customers.

retention_bridge

What it returns: Follows the customers paying on the opening date and returns exact gross and net revenue retention, losses, expansion and contraction.

Example prompt: Of customers paying on January 1, how much MRR remained on October 31? Show gross and net retention and the largest customer changes.

Limits and how to read them:

  • Up to 5 years within calculated history.
  • An endpoint comparison; new customers are excluded.
  • The customer view is the 50 largest absolute changes. The summary totals describe the full population; the displayed rows may not.

customer_breakdown

What it returns: Splits the opening paying base by MRR tier, tenure, billing interval, subscription count or card country, then follows each group to the closing date.

Example prompt: Compare January 1–October 31 gross/net retention for small, mid-size and large customers; state the MRR tier cutoffs. Repeat by customer tenure.

Limits and how to read them:

  • Up to 5 years. New customers are excluded.
  • Groups are disjoint and come with an exact total.
  • Default MRR cuts are the median and the 90th percentile.
  • Country is today’s active-card country and may be unavailable.
  • Optional current-member segment, without a plan filter.

Customer journeys: lifecycle_timing and plan_transitions

How long until a customer first upgrades, what share of churned customers downgraded first, and which plans do customers move between?

lifecycle_timing

What it returns: Shows when churn, upgrades and other events occur by tenure, and follows first events forward or backward with mature denominators.

Example prompt: Of customers acquired January–June 2026, what share upgraded within 90 days, and what was the median wait among those who did? Also, what share of October churn customers downgraded in the prior 90 days?

Limits and how to read them:

  • Up to 1 year of anchor/event dates; follow window 1–365 days.
  • Event-age shares are not churn rates: an event-age distribution has no at-risk denominator.
  • Upgrades include added subscriptions and quantity increases.
  • A sequence (for example, a downgrade before churn) is an association, not proof of cause.
  • Optional current-member segment, without a plan filter.
  • It has a one-year cap and event-volume limits. If it refuses a long period, narrow the range or use an eligible segment rather than substituting partial totals.

plan_transitions

What it returns: Shows from-plan/to-plan changes, the customers involved and the signed MRR moved. Same-plan moves and added subscriptions are separated out.

Example prompt: Which plan-to-plan switches drove MRR gains and losses in October? Separate those from quantity/price changes and added subscriptions.

Limits and how to read them:

  • Up to 1 year.
  • Returns the top plan pairs plus “other” and an exact total, with optional direction and plan filters.
  • Plan switches are only part of upgrades.

Revenue dependence and exposure: revenue_concentration and revenue_exposure

How much MRR comes from your top 10 customers, how many customers make up 80%, and what does the current risk classification flag?

revenue_concentration

What it returns: Exact top-1, top-5 and top-10 customer shares of MRR, or of positive existing-customer net expansion, plus the number of customers needed to reach a chosen share.

Example prompt: At October 31, what share of MRR came from our top 10 customers, and how many customers accounted for 80%?

Limits and how to read them:

  • No segments.
  • With basis net_expansion, net expansion means positive endpoint growth, excluding new customers. That is different from gross expansion events.
  • Top sets overlap.
  • The customer view is capped at 50.

revenue_exposure

What it returns: Current flagged customer MRR, heuristic weighted loss, the primary risk channels and customer evidence. The result shows scored MRR, exposed MRR, heuristic loss, customer count and exposed share together.

Example prompt: How much scored MRR is flagged as at risk now, which channels explain it, and which exposed customers have the largest balances?

Limits and how to read them:

  • Uses current stored health features only; coverage and timestamps are included in the result.
  • Exposure is not confirmed loss, and heuristic loss is not a forecast. It is a heuristic with no calibrated loss forecast and no defined horizon, so it doesn’t predict next month’s loss.
  • No renewal calendar or scheduled-cancellation analysis.
  • It can refuse when features are missing or the candidate population is too large.

Stability, segments and scenarios: series_stats, population_compare and growth_scenarios

Which segments have the most variable MRR, how do saved segments compare, and what happens to MRR over 12 months under explicit growth assumptions?

series_stats

What it returns: Mean, median, extremes, variability and trend over whole months or quarters. In segment mode, it ranks saved segments on supported metric levels.

Example prompt: Which saved segments had the most variable MRR from January through October 2026? Show trend and active customers alongside variability.

Limits and how to read them:

  • 3–36 whole months, or at least 3 whole quarters, within 3 years. Partial periods are dropped.
  • Segment mode returns the top 50, on supported levels and counts, not rates.
  • Overlapping segments have no total.

population_compare

What it returns: Compares one built-in metric across 2–4 saved segments, including previous-period or previous-year changes.

Example prompt: Compare MRR for our SMB, Mid-market and Enterprise saved segments in October against September.

Limits and how to read them:

  • Up to 1 year.
  • Uses saved-segment semantics, and populations can overlap. That is why segment totals can exceed the account: never add comparison rows together.
  • Segments are not fixed acquisition cohorts.

growth_scenarios

What it returns: Projects monthly MRR from an observed baseline using explicit, constant churn, contraction, expansion and new-MRR assumptions.

Example prompt: Starting from October 31 MRR, model 12 months with 2% monthly MRR churn, 0.5% contraction, 1% expansion and $10,000 of new MRR per month. Compare churn at 1%.

Limits and how to read them:

  • 1–24 months.
  • A deterministic scenario, not a forecast. It applies only the assumptions you supply: no seasonality and no automatic estimation.
  • Scenario new MRR is supplied in account-currency minor units; follow the unit metadata in the result.
  • New MRR is not cash revenue.
  • For sensitivity analysis, make multiple calls.

Multi-tool workflows: four examples that combine tools

The tools are designed to be combined in one conversation. Each example below names the tools an assistant would use and the caveat that comes with the combination.

Is our newer growth better?

Example prompt: Compare customers acquired January–March with April–June at age 3 months. Show customer and revenue retention and ARPU, then break the acquisition outcomes out by initial billing interval and discount bucket. Keep populations and denominators explicit.

Tools: retention_cohorts and acquisition_outcomes. How to read it: this compares equal ages. It does not establish that a billing interval or discount caused the outcome.

Are we relying on a few existing customers?

Example prompt: For the customers paying on January 1, explain the MRR change through October 31. How much positive net expansion came from the top 5 contributors? Show the largest customer changes.

Tools: retention_bridge and revenue_concentration with basis net_expansion. How to read it: positive endpoint growth is different from gross expansion events. Customer lists are samples; use the summaries for full totals.

Where should we investigate retention?

Example prompt: Compare January–October retention by opening MRR tier and tenure. Then show the age distribution of churn events in October and the share of October churn customers with a downgrade in the prior 90 days.

Tools: customer_breakdown and lifecycle_timing. How to read it: the breakdown has a fixed opening population; the event-age distribution has no at-risk denominator. The sequence is an association, not proof of cause.

Which segments and plans deserve attention?

Example prompt: Rank saved segments by MRR variability across January–October. Compare the October customer churn rates for three selected segments against September. List every plan with at least 30 active customers in ascending churn-rate order.

Tools: series_stats, population_compare and the improved metric_by_plan. How to read it: segment rankings of levels are distinct from rate comparisons. The plan active-customer threshold is a size filter, not a historical rate denominator.

What improved in the existing MCP tools?

These changes improve tools that were already in the catalog. They are not counted among the 13 additions.

  • Complete plan rankings: metric_by_plan now supports ascending and descending ordering and view: all, with 50 plans per page, min_customers and cursors. Follow every page for a complete ranking. This mode is by plan, not plan group, and shares use the eligible plans’ sum.
  • Complete segment discovery: segment_list supports view: all and cursor paging, with the last-known count, the count timestamp and freshness. A stale count is not current membership.
  • Exact cohort totals: acquisition, trial and eligible retention-cohort outputs include total: true rows calculated from combined denominators. Don’t average cohort rates. Retention-cohort totals require every selected cohort to have reached the requested age.
  • Calculated-date boundaries: metric reads bound themselves to the account’s calculated days and disclose shortened ranges. An uncalculated day is not presented as a zero, and ranges without calculated days are refused.
  • Corrected original MCP results: summary net revenue retention, cohort monetary units and cohort dates were corrected.
  • Customer lookup and movements: customer search also finds provider names, and movement-customer reads cover every movement/metric pair they advertise.

Design principles behind the Baremetrics MCP tools

An AI assistant is only as reliable as the numbers it is handed. These principles run through the 13 new tools and the improvements above.

Exact denominators and totals

The tools return calculated rates together with their denominators, amounts and totals, so the assistant doesn’t have to rebuild them. Cohort outputs include total: true rows calculated from combined denominators rather than averaged rates. customer_breakdown returns disjoint groups with an exact total, and plan_transitions returns the top plan pairs plus “other” and an exact total. Where a customer view is capped at 50 rows, the summary totals still describe the full population. The same idea applies to the RevOS MRR tools: MRR movements reconcile, so starting MRR + new + expansion + reactivation − contraction − churn = ending MRR.

Calculated-date boundaries

Metric reads stay inside the account’s calculated days and disclose when a range was shortened. An uncalculated day is never presented as zero, and a range with no calculated days is refused. Cohort checkpoints that haven’t been reached come back as null, and only mature customers or episodes enter checkpoint rates.

Refusals instead of partial answers

When a question is out of range, the tool says why and what to do instead. lifecycle_timing refuses periods beyond its one-year cap or event-volume limits; revenue_exposure can refuse missing features or an oversized candidate population. The guidance is to narrow the range or use an eligible segment, not to silently substitute partial totals.

Unit metadata

The 17 RevOS tools that shipped before this release take every figure from the same calculations as the metric pages, with its unit, so their answers match what you see in Baremetrics. Assistants should follow each result’s unit metadata: rates commonly use basis points (10,000 = 100%), and scenario new MRR is supplied in account-currency minor units.

Read-only

All 48 tools are read-only. No tool changes anything in the account.

Permission checks

Customer-sensitive tools and segment rankings enforce customer-visibility checks, and tool visibility does not override account permissions. Public dashboard viewers don’t get the customer or Revenue Pulse tools.

An assistant can still misinterpret what a tool returns. Confirm specific numbers against your own exports before making important business decisions.

Where the 13 new tools fit in the full catalog

Tool setCountBest for
Original API tools18Raw records, as the Baremetrics API returns them: individual charges, subscriptions, events, plan details and cohorts
RevOS tools (before this release)17Metric series and definitions, MRR movements, plan and customer views, segments, Revenue Pulse and benchmarks
RevOS tools (this release)13Growth quality, retention, customer journeys, revenue dependence and exposure, stability and scenarios
Total4818 original API tools and 30 RevOS tools

For prompts that use the original tools, see 15 Baremetrics MCP use cases.

More MCP tools are coming

The playground gives you one place to discover what Baremetrics MCP can do as the catalog grows. More tools are on the way, and more questions you can answer with your Baremetrics data. This release doesn’t come with a delivery date or a list of upcoming capabilities.

Frequently Asked Questions

  • Does the Baremetrics MCP change account data?

    No. All 48 tools are read-only. An AI assistant connected to the MCP can read your Baremetrics data, but no tool changes anything in the account.

  • Do I need to set up an AI assistant to try the tools?

    No. The MCP Playground in Settings → Integrations → MCP lets you browse the tools, run them on your account’s data with prefilled examples, and read the results before you connect an assistant.

  • Which AI clients can connect to the Baremetrics MCP?

    Desktop clients: Claude Desktop, Claude Code, Cursor and Codex, plus other clients over STDIO through mcp-remote. Web-based clients such as ChatGPT and Claude.ai in the browser aren’t supported yet, because they connect over OAuth and the Baremetrics MCP server currently uses header-based authentication.

  • Why does my new cohort have no rate yet?

    Its observation window is incomplete. Use the mature count and the missing-checkpoint information, and don’t treat missing as zero.

  • Are discounts or annual plans causing better retention?

    These tools report observed outcomes, not causal effects. Acquisition groupings use metadata at acquisition, and historical plan metadata is not versioned.

  • Why do segment totals exceed the account total?

    Saved segments can overlap and use their metric-page membership semantics. Never add segment comparison or ranking rows together.

  • Is Revenue Exposure a prediction of next month’s loss?

    No. It classifies stored health features, discloses coverage and timestamps, and has no calibrated loss horizon. It can refuse when features are missing or the candidate population is too large.

  • Does a growth scenario predict our actual growth?

    No. It applies the explicit constant assumptions you supply. Use multiple calls for sensitivity analysis.

  • Can I get every customer behind a result?

    Several analytical customer views cap at 50 rows. Their exact summary totals describe the full population; the displayed customer rows may not.

  • Can a public dashboard viewer see customer analysis?

    Customer-sensitive tools and segment rankings enforce customer-visibility checks, and tool visibility does not override account permissions. Public dashboard viewers don’t get the customer or Revenue Pulse tools.

  • What units do the results use?

    Follow each result’s unit metadata. Rates commonly use basis points, where 10,000 equals 100%. Scenario new MRR is supplied in account-currency minor units.

  • Why does a lifecycle query refuse a long period?

    It has a one-year cap and event-volume limits. Narrow the range or use an eligible segment; don’t silently substitute partial totals.

  • Why can’t I see the new tools in my assistant?

    Reconnect the Baremetrics connector or restart the assistant to refresh tool discovery.

Luke Marshall

Luke Marshall is the CEO of Baremetrics. His expertise spans strategic advisory roles at firms like Xenon Partners and DreamFactory Software and he has established himself as a thought leader in the SaaS Metrics space. His career is marked by a commitment to driving growth and operational excellence.