> ## Documentation Index
> Fetch the complete documentation index at: https://retain.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect MCP

> Let Claude, Cursor and other AI agents read your churn data and act on it

Retain speaks [MCP](https://modelcontextprotocol.io). Point any MCP client at [`@retain-so/mcp-server`](https://github.com/retain-so/mcp-server) and your agent can answer "who is about to churn?" without you opening a dashboard.

The server holds no business logic and no database. It translates MCP tool calls into HTTP requests against Retain's `/agent/*` API, authenticated with an agent key you create and can revoke at any time.

<Note>
  Agent keys are **not** the same as the Project Token used for
  [ingest](/docs/guides/authentication). A **read** key can only query. A **read &
  write** key can also mark alerts as contacted and archive them.
</Note>

## What you can ask

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

## Set it up

<Steps>
  <Step title="Create an agent key">
    In Retain, go to **Settings → [Agent
    keys](https://retain.so/dashboard/settings?tab=agent-keys)** and create a
    key. Pick **read** for query-only, or **read & write** to let the agent take
    actions.

    The key starts with `rk_agent_` and is shown once, so copy it before closing
    the dialog.
  </Step>

  <Step title="Add it to your MCP client">
    Drop your key into the config for your client. Claude Desktop
    (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and Windsurf
    (`~/.codeium/windsurf/mcp_config.json`) all take the same JSON.

    <CodeGroup>
      ```bash Claude Code theme={"theme":"vesper"}
      claude mcp add retain --env RETAIN_API_KEY=rk_agent_xxx -- npx -y @retain-so/mcp-server
      ```

      ```json Claude Desktop theme={"theme":"vesper"}
      {
        "mcpServers": {
          "retain": {
            "command": "npx",
            "args": ["-y", "@retain-so/mcp-server"],
            "env": { "RETAIN_API_KEY": "rk_agent_xxx" }
          }
        }
      }
      ```

      ```json Cursor theme={"theme":"vesper"}
      {
        "mcpServers": {
          "retain": {
            "command": "npx",
            "args": ["-y", "@retain-so/mcp-server"],
            "env": { "RETAIN_API_KEY": "rk_agent_xxx" }
          }
        }
      }
      ```

      ```json Windsurf theme={"theme":"vesper"}
      {
        "mcpServers": {
          "retain": {
            "command": "npx",
            "args": ["-y", "@retain-so/mcp-server"],
            "env": { "RETAIN_API_KEY": "rk_agent_xxx" }
          }
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Restart and ask something">
    Restart the client so it picks up the new server, then ask it who is about
    to churn. A first `npx` run downloads the package, so give it a few seconds.
  </Step>
</Steps>

## Tools

| Tool                    | Type  | What it does                            |
| ----------------------- | ----- | --------------------------------------- |
| `get_at_risk_customers` | read  | Customers by churn risk, ordered by MRR |
| `get_customer_details`  | read  | Full profile for one customer           |
| `get_mrr_at_risk`       | read  | MRR at risk, plus alert counts by level |
| `get_active_alerts`     | read  | Active alerts, with their risk factors  |
| `get_churn_metrics`     | read  | Churn rate, MRR churned, expansion, NRR |
| `mark_alert_contacted`  | write | Mark an alert as contacted              |
| `archive_alert`         | write | Archive a resolved alert                |

`get_at_risk_customers` defaults to Critical and High risk, and `get_customer_details` takes either a customer id or a name. Coming soon: `send_retention_email`, to trigger a templated retention email.

## Configuration

| Variable         | Required | Default                 | Description                                     |
| ---------------- | -------- | ----------------------- | ----------------------------------------------- |
| `RETAIN_API_KEY` | yes      |                         | Agent key from **Settings → Agent keys**.       |
| `RETAIN_API_URL` | no       | `https://api.retain.so` | Override the API base URL (staging, self-host). |

## Troubleshooting

* **`RETAIN_API_KEY is not set`.** The client launched the server without the env var. Check that `env` sits inside the `retain` entry in your config, not next to it.
* **`Invalid or revoked agent key`.** The key was revoked, or belongs to another organization. Create a new one in **Settings → Agent keys**.
* **`This agent key is read-only`.** The agent tried an action tool with a read key. Create a read & write key and swap it in.
* **The server never shows up.** MCP clients read their config at startup, so restart fully after editing it. The server needs Node 22 or newer.

## Next steps

<CardGroup cols={2}>
  <Card title="Source on GitHub" icon="github" href="https://github.com/retain-so/mcp-server">
    Read the code, open an issue, or contribute a tool.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/guides/authentication">
    The Project Token used to send events, which is a different key.
  </Card>
</CardGroup>