Retain So

io.github.retain-soPublished by GitHub account retain-sov0.1.2Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Retain MCP server lets an AI assistant query churn risk, customer health, MRR at risk and alerts in Retain, and mark or archive alerts.

What you can do
Query at-risk customers by risk level, ordered by MRR, and pull a single customer's full profile by id or name. Read MRR at risk with active-alert counts by risk level, and list active alerts by priority with risk factors and outreach state. Summarize churn metrics: churn rate, MRR churned, expansion/contraction and net revenue retention. Act on alerts by marking one as contacted or archiving a resolved one (requires a read and write key).
When to use it
Useful for customer success, support or revenue teams already using Retain who want to ask an agent in natural language who is about to churn, how much MRR is at risk, and to log outreach without opening the dashboard.
Requirements
Runs locally via npx from the npm package @retain-so/mcp-server, so Node.js is needed. Requires a Retain agent key passed in the RETAIN_API_KEY environment variable, created under Settings → Agent keys; choose read for query-only or read & write to allow actions. Network access to the Retain API is required; RETAIN_API_URL can override the API base URL.
Before you install
The RETAIN_API_KEY is a secret shown only once and grants access to your Retain customer data; a read & write key also lets the agent change alert state. The write tools mark alerts as contacted and archive alerts, which modifies data in Retain. Tool calls are translated into HTTP requests to Retain's API, so customer data is sent to that service.

Installation

In SourceWeft

  1. Open Retain So in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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 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

ToolTypeWhat it does
get_at_risk_customersreadCustomers by churn risk (Critical/High/Stable/Healthy), ordered by MRR. Defaults to Critical + High.
get_customer_detailsreadFull profile for one customer by id or name.
get_mrr_at_riskreadTotal MRR at risk plus active-alert counts by risk level.
get_active_alertsreadActive alerts by priority, with risk factors and outreach state.
get_churn_metricsreadChurn rate, MRR churned, expansion/contraction, net revenue retention.
mark_alert_contactedwriteMark an alert as contacted.
archive_alertwriteArchive 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

VariableRequiredDefaultDescription
RETAIN_API_KEYyes(none)Agent key from Settings → Agent keys.
RETAIN_API_URLnohttps://api.retain.soOverride the API base URL (self-host / staging).

Development

bash
npm installnpm run dev        # run from source with tsxnpm 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

Source: README.md at commit 627800e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts