# retain-so/mcp-server [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/retain-so/mcp-server  
**GitHub Stars:** 1  
**npm Downloads (last month):** 118  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-155

## Description
Model Context Protocol server for Retain: let AI agents query churn risk and act on retention.

## Tools
Capabilities this server exposes over MCP:

- **get_at_risk_customers** — List customers by churn risk level, ordered by MRR at risk. Use to answer "which customers are at critical/high risk?".
- **get_customer_details** — Get the full profile for one customer by id or name: plan, health score, risk level, seats, activity trend and recent alerts.
- **get_mrr_at_risk** — Total monthly recurring revenue at risk plus active-alert counts by risk level. A quick executive snapshot.
- **get_active_alerts** — List active (non-archived) alerts ordered by priority, with customer, risk factors, MRR at risk and outreach state.
- **get_churn_metrics** — Consolidated metrics for the current period: churn rate, MRR churned, new/expansion/contraction MRR and net revenue retention.
- **mark_alert_contacted** — 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.
- **archive_alert** — Archive a resolved alert, removing it from the attention queue. Requires a read+write agent key.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","@retain-so/mcp-server"],
    "env": {
      "RETAIN_API_KEY": "",
      "RETAIN_API_URL": ""
    }
  }
}
```

**Requires environment variables:** `RETAIN_API_KEY`, `RETAIN_API_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What retain-so/mcp-server MCP server does

The retain-so/mcp-server MCP server exposes Retain data and selected alert actions through the Model Context Protocol. It is intended for agents that need to answer questions about customer churn risk, revenue exposure, customer health, and outreach status.

Read operations cover customers in four risk categories: Critical, High, Stable, and Healthy. Risk results are ordered by MRR, and the customer query defaults to Critical and High customers. An agent can also retrieve a complete customer profile using an ID or name, inspect active alerts, and review churn and retention metrics.

The retain-so/mcp-server MCP server also includes two write operations. An agent can mark an alert as contacted or archive an alert that has been resolved. These operations require a Retain agent key with read-and-write permissions.

## How it works

The package runs as an MCP server and acts as a translation layer rather than an independent data store. It receives tool calls from an MCP client and sends corresponding HTTP requests to Retain's public `/agent/*` API. The server contains no business logic and does not maintain a database.

A typical interaction combines tools. For example, an agent can first retrieve total MRR at risk and alert counts, then request the highest-value at-risk customers for more detail. It can also list active alerts with their priority, risk factors, and outreach state before updating an alert after a customer contact.

## Setup and configuration

Create an agent key in Retain under Settings → Agent keys. Choose read access for query-only use, or read and write access if the agent must update alerts. The key is displayed once and must be supplied through the `RETAIN_API_KEY` environment variable.

The package can be launched with `npx -y @retain-so/mcp-server`. Claude Code uses an `claude mcp add` command, while Claude Desktop, Cursor, and Windsurf can define the command and environment variable in their MCP configuration files. Restart the client after adding the configuration.

`RETAIN_API_URL` is optional and defaults to `https://api.retain.so`. It can point the server at another API base URL, such as a self-hosted or staging endpoint.

## Tools and capabilities

The retain-so/mcp-server MCP server provides these tools:

- `get_at_risk_customers`: Filters customers by churn-risk level and orders them by MRR. The default levels are Critical and High.
- `get_customer_details`: Retrieves the full profile for a customer identified by ID or name.
- `get_mrr_at_risk`: Returns total MRR at risk and active-alert counts grouped by risk level.
- `get_active_alerts`: Lists active alerts by priority, including risk factors and outreach state.
- `get_churn_metrics`: Reports churn rate, churned MRR, expansion, contraction, and net revenue retention.
- `mark_alert_contacted`: Records that an alert has been contacted.
- `archive_alert`: Archives a resolved alert.

The first five tools provide read access. The final two change alert state and therefore require a read-and-write key.

## Limitations and notes

The server only exposes the tools listed above.

The server depends on Retain's API and a valid agent key. It does not itself calculate churn metrics, store customer records, or implement a separate database. Write actions are limited to marking alerts contacted and archiving alerts; broader customer or outreach mutations are not documented.

_Full upstream README: https://allmcps.com/mcp/mcp-server-155/readme_