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 Playground | Settings → 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 tools | 13 tools for growth quality, existing-customer retention, customer journeys, revenue dependence and exposure, stability and scenarios |
| Catalog | 48 tools in total: 18 original API tools and 30 RevOS tools |
| Access | Read-only. No tool changes anything in the account |
| Existing tools | Complete plan rankings and segment discovery, exact cohort totals, calculated-date boundaries and corrected results |
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.
If an account is missing a required record or enough calculated history, the playground explains what is missing instead of inserting a fake ID.
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:
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.
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:
lk_.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.
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>"
Add the entry to ~/.cursor/mcp.json:
{
"mcpServers": {
"baremetrics": {
"url": "https://app.baremetrics.com/mcp",
"headers": {
"Authorization": "Bearer <BM_API_KEY>"
}
}
}
}
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>"
]
}
}
}
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"
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 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.
| Tool | Question it answers | Key limits |
|---|---|---|
acquisition_outcomes | Do newer acquisition groups retain better at the same age? | Up to 1 year of acquisition dates; mature customers only; observational |
retention_cohorts | Customer and revenue retention curves by cohort age | Up to 12 acquisition months; ages 0–24; missing checkpoints are null |
trial_cohorts | Which trials convert and keep paying? | Up to 1 year of trial starts; episodes, not unique customers |
discount_outcomes | What happens to discounted customers? | Up to 5 years; no segments; not causal |
retention_bridge | How much opening MRR remained? | Up to 5 years; new customers excluded; 50 largest changes shown |
customer_breakdown | Retention by customer size, tenure, interval, subscription count or country | Up to 5 years; disjoint groups with an exact total |
lifecycle_timing | When do churn and upgrades happen by tenure? | Up to 1 year; event-age shares are not churn rates |
plan_transitions | Which plans do customers move between? | Up to 1 year; top pairs plus “other” and an exact total |
revenue_concentration | How dependent is MRR on the top customers? | No segments; top sets overlap; 50-row customer view |
revenue_exposure | How much MRR does the current risk classification flag? | Current health features only; exposure is not confirmed loss |
series_stats | How stable is a metric, and which segments vary most? | 3–36 whole months; partial periods dropped |
population_compare | How does a metric compare across 2–4 saved segments? | Up to 1 year; segments can overlap, so never add rows together |
growth_scenarios | What 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.
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?
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:
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:
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:
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:
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.
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:
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:
How long until a customer first upgrades, what share of churned customers downgraded first, and which plans do customers move between?
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:
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:
How much MRR comes from your top 10 customers, how many customers make up 80%, and what does the current risk classification flag?
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:
net_expansion, net expansion means positive endpoint growth, excluding new customers. That is different from gross expansion events.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:
Which segments have the most variable MRR, how do saved segments compare, and what happens to MRR over 12 months under explicit growth assumptions?
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:
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:
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:
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.
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.
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.
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.
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.
These changes improve tools that were already in the catalog. They are not counted among the 13 additions.
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.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.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.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.
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.
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.
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.
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.
All 48 tools are read-only. No tool changes anything in the account.
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.
| Tool set | Count | Best for |
|---|---|---|
| Original API tools | 18 | Raw records, as the Baremetrics API returns them: individual charges, subscriptions, events, plan details and cohorts |
| RevOS tools (before this release) | 17 | Metric series and definitions, MRR movements, plan and customer views, segments, Revenue Pulse and benchmarks |
| RevOS tools (this release) | 13 | Growth quality, retention, customer journeys, revenue dependence and exposure, stability and scenarios |
| Total | 48 | 18 original API tools and 30 RevOS tools |
For prompts that use the original tools, see 15 Baremetrics MCP use cases.
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.