Skip to main content
Glama
Retain MCP Server

Retain MCP Server

Official
by retain-so

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

Related MCP server: Custify MCP Server

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

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

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

Available Tools

8 tools
add_customer_noteAdd customer noteB

Add a note to a customer's active alert. Useful to document outreach done outside Retain. Requires a read+write agent key.

Inputs: content (required), customer_id (required).

archive_alertArchive alertA

Archive a resolved alert, removing it from the attention queue. Requires a read+write agent key.

Inputs: alert_id (required), reason.

get_active_alertsGet active alertsA

List active (non-archived) alerts ordered by priority, with customer, risk factors, MRR at risk and outreach state.

Inputs: limit.

get_at_risk_customersGet at-risk customersA

List customers by churn risk level, ordered by MRR at risk. Use to answer "which customers are at critical/high risk?".

Inputs: limit, risk_level.

get_churn_metricsGet churn metricsA

Consolidated metrics for the current period: churn rate, MRR churned, new/expansion/contraction MRR and net revenue retention.

Inputs: no named parameters.

get_customer_detailsGet customer detailsA

Get the full profile for one customer by id or name: plan, health score, risk level, seats, activity trend and recent alerts.

Inputs: customer (required).

get_mrr_at_riskGet MRR at riskA

Total monthly recurring revenue at risk plus active-alert counts by risk level. A quick executive snapshot.

Inputs: no named parameters.

mark_alert_contactedMark alerts as contactedA

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.

Inputs: alert_ids (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of churn management: customer lists by risk, individual customer profiles, MRR risk summary, active alerts, churn metrics, and alert actions (note, mark contacted, archive). No two tools have overlapping purposes, and descriptions clearly differentiate them.

    Naming Consistency5/5

    All read operations follow a consistent 'get_' prefix, while write operations use descriptive verb+nouns (add_customer_note, mark_alert_contacted, archive_alert). The naming is uniformly snake_case and predictable, making it easy for agents to infer tool behavior from names.

    Tool Count5/5

    With 8 tools, the set is well-scoped for a churn management server. It covers essential read operations (customer lists, details, metrics, alerts) and write operations (note, contacted, archive) without being bloated or insufficient. The count is appropriate for the domain.

    Completeness4/5

    The tool set covers the core workflow of identifying at-risk customers, monitoring alerts, and managing outreach states. Minor gaps exist, such as the inability to create or resolve alerts programmatically, but the available tools provide sufficient functionality for typical monitoring and action tasks.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Connects AI assistants to Custify customer success data for querying account metrics, health scores, and usage trends. It also supports taking actions such as creating notes, managing tasks, and triggering playbooks.
      15
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with RetainQ workspaces, including querying retention metrics, managing flows, analyzing churn data, and handling customers, offers, opportunities, and feedback.
      12 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI assistant to answer customer-success questions by synthesizing simulated billing, support ticket, and product usage data into composite churn-risk scores, bands, and plain-language explanations for fictional accounts. It exposes raw-data tools, a synthesis tool, and a methodology resource so users can list at-risk accounts or get a per-account health summary.
      4
      MIT