Retain MCP Server
OfficialThis server connects your AI agent to Retain for monitoring customer churn risk, analyzing revenue metrics, and taking action on at-risk accounts in natural language.
Read capabilities:
get_at_risk_customers— List customers by churn risk level (Critical, High, Stable, Healthy), ordered by MRR at risk, with filtering and limiting.get_customer_details— Retrieve a full customer profile by ID or name, including plan, health score, risk level, seats, activity trend, and recent alerts.get_mrr_at_risk— Get total MRR at risk and active-alert counts by risk level.get_active_alerts— List non-archived alerts ordered by priority, including customer, risk factors, MRR at risk, and outreach state.get_churn_metrics— View current-period churn metrics: churn rate, MRR churned, expansion/contraction, and net revenue retention.
Write capabilities (requires read+write API key):
mark_alert_contacted— Mark one or more alerts as contacted, with timestamp (up to 100 at once).archive_alert— Archive a resolved alert, optionally with a reason, to remove it from the attention queue.add_customer_note— Attach a note to a customer's active alert to document outreach or context recorded outside Retain.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Retain MCP Server Which customers are at critical risk?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Retain MCP Server
Let your AI agent see who is about to churn, and do something about it.
@retain-so/mcp-server connects Retain to any MCP client (Claude Code, Claude Desktop, Cursor, Windsurf, and friends). Ask in natural language which customers are at risk, pull a customer's full health profile, check MRR at risk, and log outreach, all without opening the dashboard.
Retain is an AI-first churn prevention and customer analytics platform. This server is the bridge between your agent and your Retain data.
What you can ask your agent to do
Read:
"Which customers are at critical risk this week?"
"Show me my high-risk customers ordered by MRR."
"What's my total MRR at risk, broken down by risk level?"
"Pull the full profile for Acme Inc."
"List the active alerts I haven't contacted yet."
"Summarize this month's churn metrics and net revenue retention."
Act (needs a read+write key):
"Mark the alert for Globex as contacted."
"Archive the resolved alert for Initech."
Related MCP server: Custify MCP Server
Setup (under 5 minutes)
In Retain, go to Settings → Agent keys and create a key. Pick read for query-only, or read & write to let the agent take actions. Copy it (it is shown once).
Add the snippet for your client below.
Restart the client and ask your first question.
Claude Code
claude mcp add retain --env RETAIN_API_KEY=rk_agent_xxx -- npx -y @retain-so/mcp-serverClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"retain": {
"command": "npx",
"args": ["-y", "@retain-so/mcp-server"],
"env": { "RETAIN_API_KEY": "rk_agent_xxx" }
}
}
}Cursor / Windsurf (.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"retain": {
"command": "npx",
"args": ["-y", "@retain-so/mcp-server"],
"env": { "RETAIN_API_KEY": "rk_agent_xxx" }
}
}
}Tools
Tool | Type | What it does |
| read | Customers by churn risk ( |
| read | Full profile for one customer by id or name. |
| read | Total MRR at risk plus active-alert counts by risk level. |
| read | Active alerts by priority, with risk factors and outreach state. |
| read | Churn rate, MRR churned, expansion/contraction, net revenue retention. |
| write | Mark an alert as contacted. |
| write | Archive a resolved alert. |
Coming soon: send_retention_email (trigger a templated retention email).
Example conversation
You: Who's about to churn and how much money is on the line?
Agent: (calls
get_mrr_at_risk, thenget_at_risk_customers) You have $4,200 MRR at risk across 7 active alerts. The two biggest are Acme Inc ($900, critical, 18 days inactive) and Globex ($650, high).You: I emailed Acme today, mark their alert as contacted.
Agent: (calls
mark_alert_contacted) Done. Acme's alert is now marked as contacted.
Configuration
Variable | Required | Default | Description |
| yes | (none) | Agent key from Settings → Agent keys. |
| no |
| Override the API base URL (self-host / staging). |
Development
npm install
npm run dev # run from source with tsx
npm run build # bundle to dist/
npm run typecheckThe server holds no business logic and no database. It only translates MCP tool calls into HTTP requests against Retain's public /agent/* API. Contributions and new tools are welcome.
License
MIT
Available Tools
8 toolsadd_customer_noteAdd customer noteB
Add a note to a customer's active alert. Useful to document outreach done outside Retain. Requires a read+write agent key.
Inputs: content (required), customer_id (required).
archive_alertArchive alertA
Archive a resolved alert, removing it from the attention queue. Requires a read+write agent key.
Inputs: alert_id (required), reason.
get_active_alertsGet active alertsA
List active (non-archived) alerts ordered by priority, with customer, risk factors, MRR at risk and outreach state.
Inputs: limit.
get_at_risk_customersGet at-risk customersA
List customers by churn risk level, ordered by MRR at risk. Use to answer "which customers are at critical/high risk?".
Inputs: limit, risk_level.
get_churn_metricsGet churn metricsA
Consolidated metrics for the current period: churn rate, MRR churned, new/expansion/contraction MRR and net revenue retention.
Inputs: no named parameters.
get_customer_detailsGet customer detailsA
Get the full profile for one customer by id or name: plan, health score, risk level, seats, activity trend and recent alerts.
Inputs: customer (required).
get_mrr_at_riskGet MRR at riskA
Total monthly recurring revenue at risk plus active-alert counts by risk level. A quick executive snapshot.
Inputs: no named parameters.
mark_alert_contactedMark alerts as contactedA
Advance one or more alerts to the "contacted" outreach state with a timestamp. Pass a single id to mark one alert, or several to mark them in one call. Requires a read+write agent key.
Inputs: alert_ids (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct aspect of churn management: customer lists by risk, individual customer profiles, MRR risk summary, active alerts, churn metrics, and alert actions (note, mark contacted, archive). No two tools have overlapping purposes, and descriptions clearly differentiate them.
All read operations follow a consistent 'get_' prefix, while write operations use descriptive verb+nouns (add_customer_note, mark_alert_contacted, archive_alert). The naming is uniformly snake_case and predictable, making it easy for agents to infer tool behavior from names.
With 8 tools, the set is well-scoped for a churn management server. It covers essential read operations (customer lists, details, metrics, alerts) and write operations (note, contacted, archive) without being bloated or insufficient. The count is appropriate for the domain.
The tool set covers the core workflow of identifying at-risk customers, monitoring alerts, and managing outreach states. Minor gaps exist, such as the inability to create or resolve alerts programmatically, but the available tools provide sufficient functionality for typical monitoring and action tasks.
Maintenance
Related MCP Connectors
Your go-to-market plan, plays and opportunities from gtm.help, inside any AI agent.
Customer-context and ops layer for AI agents
AI agents that support, onboard, convert and retain every user across helpdesk, CRM and billing.
CRM, inbox, meetings, revenue intelligence, analytics and automations for AI agents.
Related MCP Servers
- FlicenseBqualityBmaintenanceProvides access to Vitally customer success platform data, enabling users to search accounts and users, view health scores, manage conversations and tasks, and create notes through natural language interactions.112-
- AlicenseAqualityDmaintenanceConnects AI assistants to Custify customer success data for querying account metrics, health scores, and usage trends. It also supports taking actions such as creating notes, managing tasks, and triggering playbooks.153MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with RetainQ workspaces, including querying retention metrics, managing flows, analyzing churn data, and handling customers, offers, opportunities, and feedback.12 npmMIT
- AlicenseAqualityCmaintenanceEnables an AI assistant to answer customer-success questions by synthesizing simulated billing, support ticket, and product usage data into composite churn-risk scores, bands, and plain-language explanations for fictional accounts. It exposes raw-data tools, a synthesis tool, and a methodology resource so users can list at-risk accounts or get a per-account health summary.4MIT