This server connects your AI agent to Retain for monitoring customer churn risk, analyzing revenue metrics, and taking action on at-risk accounts in natural language.
Read capabilities:
get_at_risk_customers — List customers by churn risk level (Critical, High, Stable, Healthy), ordered by MRR at risk, with filtering and limiting.
get_customer_details — Retrieve a full customer profile by ID or name, including plan, health score, risk level, seats, activity trend, and recent alerts.
get_mrr_at_risk — Get total MRR at risk and active-alert counts by risk level.
get_active_alerts — List non-archived alerts ordered by priority, including customer, risk factors, MRR at risk, and outreach state.
get_churn_metrics — View current-period churn metrics: churn rate, MRR churned, expansion/contraction, and net revenue retention.
Write capabilities (requires read+write API key):
mark_alert_contacted — Mark one or more alerts as contacted, with timestamp (up to 100 at once).
archive_alert — Archive a resolved alert, optionally with a reason, to remove it from the attention queue.
add_customer_note — Attach a note to a customer's active alert to document outreach or context recorded outside Retain.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Retain MCP Server Which customers are at critical risk?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: Vitally MCP Server
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).
Add the snippet for your client below.
Restart the client and ask your first question.
claude mcp add retain --env RETAIN_API_KEY=rk_agent_xxx -- npx -y @retain-so/mcp-serverclaude_desktop_config.json){
"mcpServers": {
"retain": {
"command": "npx",
"args": ["-y", "@retain-so/mcp-server"],
"env": { "RETAIN_API_KEY": "rk_agent_xxx" }
}
}
}.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" }
}
}
}Tool | Type | What it does |
| read | Customers by churn risk ( |
| read | Full profile for one customer by id or name. |
| read | Total MRR at risk plus active-alert counts by risk level. |
| read | Active alerts by priority, with risk factors and outreach state. |
| read | Churn rate, MRR churned, expansion/contraction, net revenue retention. |
| write | Mark an alert as contacted. |
| write | Archive a resolved alert. |
Coming soon: send_retention_email (trigger a templated retention email).
You: Who's about to churn and how much money is on the line?
Agent: (calls
get_mrr_at_risk, thenget_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.
Variable | Required | Default | Description |
| yes | (none) | Agent key from Settings → Agent keys. |
| no |
| Override the API base URL (self-host / staging). |
npm install
npm run dev # run from source with tsx
npm run build # bundle to dist/
npm run typecheckThe 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.
MIT
Add a note to a customer's active alert. Useful to document outreach done outside Retain. Requires a read+write agent key.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Note text. | |
| customer_id | Yes | Customer id (UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the auth requirement but does not disclose side effects, error conditions, or idempotency, which are important for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, front-loading the primary action in the first sentence and adding context in the second. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description lacks information about return values or error handling. It is not fully complete for an agent to reliably use without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with descriptions, resulting in 100% coverage. The tool description does not add additional meaning beyond what is already in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a note') and the target ('a customer's active alert'), with a specific use case ('document outreach done outside Retain'). It is specific and informative, though it does not explicitly differentiate from the sibling tool 'mark_alert_contacted'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context ('Useful to document outreach done outside Retain') and a prerequisite ('Requires a read+write agent key'), but lacks explicit when-not-to-use guidance or comparison to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Archive a resolved alert, removing it from the attention queue. Requires a read+write agent key.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional reason for archiving. | |
| alert_id | Yes | Alert id (UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses effect of archiving and removal from attention queue, plus auth requirement. No annotations provided, so description carries burden. Lacks details on reversibility or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded purpose, no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, prerequisite, and effect. Missing mention of return type or error cases, but adequate for a simple action with full schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds no supplementary meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'archive', resource 'resolved alert', and outcome 'removing from attention queue'. Distinguishes from sibling tools like get_active_alerts and mark_alert_contacted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions prerequisite of read+write agent key, but does not explicitly state when to use vs alternatives or when not to archive. Implicitly for resolved alerts but could be clearer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active (non-archived) alerts ordered by priority, with customer, risk factors, MRR at risk and outreach state.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of alerts to return (default 20). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes filter (non-archived) and ordering by priority. No annotations provided, so description fully covers behavioral traits; no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, every word adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema), description covers filtering, ordering, and response fields. Sufficient for agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'limit' already well-described in schema. Description adds value by listing output fields, helping infer what the parameter returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'list', resource 'active alerts', ordering by priority, and included fields. Distinguishes from siblings like 'archive_alert' (mutation) and 'get_at_risk_customers' (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly clear for listing active alerts; no explicit when/when-not, but straightforward enough. Could contrast with 'get_at_risk_customers' for risk-specific queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers by churn risk level, ordered by MRR at risk. Use to answer "which customers are at critical/high risk?".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of customers to return (default 20). | |
| risk_level | No | Risk levels to include. Omit for Critical + High. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses ordering and default risk levels but omits return format (e.g., which fields are returned), pagination details beyond limit, and sorting direction. Moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences with no wasted words. The first sentence states the core function, and the second provides a practical usage example. Perfectly structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain return values. It says 'list customers' but does not specify fields like customer name, ID, MRR amount, risk level, etc. For a list tool with two parameters, the description is incomplete regarding output structure. Also lacks any safety or side-effect disclosure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter descriptions. The tool description reinforces that omitting risk_level defaults to Critical+High, which is already in the schema. No new semantic value added beyond the schema, hence baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List customers by churn risk level' and specifies ordering by MRR at risk. It also provides a concrete usage example ('which customers are at critical/high risk?') that distinguishes it from sibling tools like get_customer_details or get_mrr_at_risk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear use case ('Use to answer...') but does not explicitly state when not to use the tool or mention alternative tools. Given the sibling tools, additional guidance on exclusions would improve score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consolidated metrics for the current period: churn rate, MRR churned, new/expansion/contraction MRR and net revenue retention.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It implies a read operation but does not define 'current period,' data freshness, permission requirements, or anything about mutability. The description is too terse for a tool with zero annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that packs all relevant information—no wasted words, front-loaded with purpose, and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately lists the metrics returned. However, it lacks details like numerical format (e.g., percentages vs. absolute) or time range definition (e.g., month-to-date). Still, for a simple metrics endpoint, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description adds value by enumerating the returned metrics (churn rate, MRR churned, net revenue retention), which goes beyond the empty schema. Baseline for 0 params is 4, and this meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides 'consolidated metrics for the current period' and lists specific metrics (churn rate, MRR churned, net revenue retention), making the purpose distinct from siblings like get_mrr_at_risk or get_at_risk_customers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention scenarios where other tools (e.g., get_mrr_at_risk) would be more appropriate, nor does it specify prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full profile for one customer by id or name: plan, health score, risk level, seats, activity trend and recent alerts.
| Name | Required | Description | Default |
|---|---|---|---|
| customer | Yes | Customer id (UUID) or name to look up. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the returned data but does not explicitly state that the tool is read-only or disclose any potential side effects, authentication requirements, or data freshness. For a read operation, this is minimally adequate but could be improved by mentioning read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the action, input, and output fields. There is no unnecessary repetition or verbose language. Every part of the sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single required parameter and no output schema, the description lists the key return fields (plan, health score, risk level, seats, activity trend, recent alerts), which is fairly complete for a profile tool. It could mention error cases or format of the output, but it is sufficient for an agent to understand what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('customer') with 100% description coverage in the schema itself. The description adds the clarification 'by id or name', but this is already hinted in the schema description. The description does not add significant semantic value beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('customer'), lists the return fields (plan, health score, risk level, seats, activity trend, recent alerts), and distinguishes from siblings like get_at_risk_customers (which returns a list) and get_active_alerts (which is about alerts). It clearly states what the tool does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to identify the customer ('by id or name') and implies use when needing a single customer's full profile. However, it does not explicitly state when to use this tool versus siblings (e.g., when you need a list of customers, use get_at_risk_customers). The guidance is clear but lacks exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Total monthly recurring revenue at risk plus active-alert counts by risk level. A quick executive snapshot.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. It discloses the output (MRR and alert counts by risk level) and positions it as a read-only snapshot, but does not cover any potential caveats, data freshness, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence states the core output, the second adds context ('quick executive snapshot'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool without output schema, the description sufficiently indicates what is returned (total MRR and alert counts by risk level). However, it does not specify the data structure or format of the risk level breakdown, which could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (vacuously). The description does not need to add parameter details; the baseline of 4 for zero-parameter tools applies as no value is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Total monthly recurring revenue at risk plus active-alert counts by risk level' and positions it as an executive snapshot, distinguishing it from sibling tools like get_at_risk_customers (customer-level) and get_active_alerts (alerts only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for a quick executive overview ('A quick executive snapshot') but provides no explicit guidance on when to use this tool versus alternatives like get_churn_metrics or get_at_risk_customers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| alert_ids | Yes | Alert ids (UUIDs). Pass one or many, up to 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. Discloses state transition with timestamp, batching limit, and auth requirement. But doesn't specify idempotency, response format, or behavior on already contacted alerts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy. Every sentence adds value: purpose, usage variants, and prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with one parameter and no output schema. Covers purpose, usage, and auth. Lacks details on response behavior or edge cases, but overall complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description reinforces that alert_ids can be single or multiple, but adds minimal meaning beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Advance') and resource ('alerts') with a clear target state ('contacted'). It distinguishes from sibling tools like 'archive_alert' (different action) and 'get_active_alerts' (read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidance: passing single vs multiple IDs, and requires a read+write agent key. Lacks explicit when-not-to-use vs alternatives, but the context is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2add_customer_notearchive_alertget_active_alertsget_at_risk_customersget_churn_metricsget_customer_detailsget_mrr_at_riskmark_alert_contactedEach 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.
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.
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.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Customer-context and ops layer for AI agents
AI-native GTM OS for B2B SaaS — account health, pipeline, renewals, territories, and benchmarks.
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
CRM, relationship intelligence, and multi-agent orchestration for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/retain-so/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
