io.github.retain-so/mcp-server

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

claude mcp add retain --env RETAIN_API_KEY=rk_agent_xxx -- npx -y @retain-so/mcp-server

Claude 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

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

Development

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