io.github.retain-so/mcp-server
Model Context Protocol server for Retain: let AI agents query churn risk and act on retention.
Open source Open in the app JSON README (API)
About
Model Context Protocol server for Retain: let AI agents query churn risk and act on retention.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- retain-so
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Stars
- 1
- Last push
- 2026-08-08T13:48:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:17
- Updated
- 2026-08-29 04:01:17
- Origin id
io.github.retain-so/mcp-server
README
# Retain MCP Server
Let your AI agent see who is about to churn, and do something about it.
`@retain-so/mcp-server` connects [Retain](https://retain.so) 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."
## Setup (under 5 minutes)
1. 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).
2. Add the snippet for your client below.
3. Restart the client and ask your first question.
### Claude Code
```bash
claude mcp add retain --env RETAIN_API_KEY=rk_agent_xxx -- npx -y @retain-so/mcp-server
```
### Claude Desktop (`claude_desktop_config.json`)
```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`)
```json
{
"mcpServers": {
"retain": {
"command": "npx",
"args": ["-y", "@retain-so/mcp-server"],
"env": { "RETAIN_API_KEY": "rk_agent_xxx" }
}
}
}
```
## Tools
| Tool | Type | What it does |
| ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------ |
| `get_at_risk_customers` | read | Customers by churn risk (`Critical`/`High`/`Stable`/`Healthy`), ordered by MRR. Defaults to Critical + High. |
| `get_customer_details` | read | Full profile for one customer by id or name. |
| `get_mrr_at_risk` | read | Total MRR at risk plus active-alert counts by risk level. |
| `get_active_alerts` | read | Active alerts by priority, with risk factors and outreach state. |
| `get_churn_metrics` | read | Churn rate, MRR churned, expansion/contraction, net revenue retention. |
| `mark_alert_contacted` | write | Mark an alert as contacted. |
| `archive_alert` | 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`, then `get_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 |
| ---------------- | -------- | ----------------------- | ------------------------------------------------ |
| `RETAIN_API_KEY` | yes | (none) | Agent key from Settings → Agent keys. |
| `RETAIN_API_URL` | no | `https://api.retain.so` | Override the API base URL (self-host / staging). |
## Development
```bash
npm install
npm run dev # run from source with tsx
npm run build # bundle to dist/
npm run typecheck
```
The 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