English Français العربية

io.github.retain-so/mcp-server

Official registry AI and agents

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

Source code Documentation

What can you do with io.github.retain-so/mcp-server?

  • "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."
  • "Mark the alert for Globex as contacted."
  • "Archive the resolved alert for Initech."

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @retain-so/mcp-server
Claude Code 
claude mcp add io-github-retain-so-mcp-server -e 'RETAIN_API_KEY=<your retain_api_key>' -- npx -y @retain-so/mcp-server@0.1.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "io-github-retain-so-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@retain-so/mcp-server@0.1.2"
            ],
            "env": {
                "RETAIN_API_KEY": "<your retain_api_key>"
            }
        }
    }
}

Environment variables

  • RETAIN_API_KEY required secret Your API key from Retain

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Retain MCP Server
  2. What you can ask your agent to do
  3. Setup (under 5 minutes)
  4. Tools
  5. Example conversation
  6. Configuration
  7. Development
  8. License

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

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

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

Frequently asked questions

What is io.github.retain-so/mcp-server?

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

How do I install io.github.retain-so/mcp-server?

It runs on your machine. In Claude Code: claude mcp add io-github-retain-so-mcp-server -e 'RETAIN_API_KEY=<your retain_api_key>' -- npx -y @retain-so/mcp-server@0.1.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.retain-so/mcp-server need an API key?

Yes. It expects RETAIN_API_KEY, which you set in its configuration.

Is io.github.retain-so/mcp-server open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.retain-so/mcp-server?

It is published by retain-so. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.