ChurnCue

Know who may leave. Understand the signal. Protect the renewal.

Production-oriented customer-retention intelligence for Archestra, powered by deterministic machine learning over MCP.

Quickstart · Architecture · Archestra setup · App prompt · Demo script

The Monday-morning problem

Customer-success teams repeatedly need to answer five questions before renewal risk becomes lost revenue:

1. Which customers are likely to cancel?

2. Who became riskier this week?

3. Which observed signals explain the change?

4. How much recurring revenue is exposed?

5. What action should the team take next?

ChurnCue converts anonymous customer-health records into a prioritized, evidence-backed rescue queue. It keeps model calculations in deterministic Python services and keeps outbound Slack notifications behind explicit human approval.

Related MCP server: MCP Self-Learning Server

Why ChurnCue

System architecture

flowchart LR
  Demo[Anonymous demo CSV]

  subgraph Archestra[Archestra]
    App[ChurnCue App]
    Orchestrator[MCP Orchestrator]
    Approval{Human approval}
  end

  subgraph Service[ChurnCue MCP]
    Load[Load + store dataset]
    Profile[Profile + validate]
    Train[Train + compare]
    Score[Score + explain]
    Report[Rescue report]
    Runtime[(Dataset + score-run state)]
  end

  Demo --> Load
  App --> Orchestrator --> Load
  Load -->|dataset_id| Profile --> Train --> Score
  Score -->|score_run_id| Report
  Load --> Runtime
  Score --> Runtime
  Train --> Metadata[(SQLite metadata)]
  Train --> Artifacts[(joblib artifacts)]
  Report --> Approval
  Approval -->|approved only| Slack[Slack MCP]

Archestra is the authenticated application interface and MCP orchestrator. ChurnCue MCP stores demo rows internally and exposes only compact dataset and score-run identifiers to the model. Slack MCP receives only messages that a human approves.

Governed rescue workflow

The block diagram follows a real customer-success request: “Which customers are most likely to leave this week, and whom should we contact first?”

1. The manager asks the business question in Archestra.

2. The Archestra agent selects only the approved ChurnCue tools. Access controls, guardrails, and activity logs govern the interaction.

3. ChurnCue MCP exposes the prediction workflow through eight bounded tools.

4. The deterministic machine-learning pipeline trains, scores, and ranks customers, returning verified scores and compact identifiers.

5. The model explains those tool-produced results without inventing calculations.

6. Archestra presents a prioritized rescue report so the manager knows whom to contact first.

Weekly review flow

Load demo → dataset_id → Profile quality → Train 3 models → experiment_id
          → Score customers → score_run_id → Compare risk → Rescue report
          → Preview Slack message → Human approval → Slack MCP sends

Quickstart

Run locally

git clone https://github.com/Bhaktabahadurthapa/ChurnCue.git
cd ChurnCue
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
python scripts/generate_demo_data.py
churncue

Verify the service:

curl http://localhost:8000/health
npx -y @modelcontextprotocol/inspector

Connect the Inspector to http://localhost:8000/mcp with Streamable HTTP.

Run with Docker

docker compose up --build -d
docker compose ps
curl http://localhost:8000/health

Stop the service with docker compose down. SQLite metadata and model artifacts remain in named volumes.

Connect to Archestra

Register a remote Streamable HTTP server in Archestra's Private MCP Registry:

Name: ChurnCue
URL:  http://host.docker.internal:8000/mcp

Linux-hosted Archestra containers may need host.docker.internal:host-gateway. Assign all eight tools to the app, then paste the ready-to-use application prompt into Archestra Chat.

MCP tool surface

Recommended call order:

load_demo_dataset → dataset_id → profile_dataset + train_models
dataset_id + experiment_id → score_customers → score_run_id
score_run_id → compare_weekly_risk + explain_risk + generate_rescue_report

Machine-learning pipeline

The included dataset contains 50 reproducible synthetic customers and no real personal data.

Configuration

All runtime variables use the CHURNCUE_ prefix. Safe defaults are documented in .env.example.

No API keys or customer credentials belong in this repository.

Security and privacy

• Anonymous CUST-* identifiers only; common PII fields are rejected at the MCP boundary.

• Dataset and score rows stay inside the ChurnCue process; MCP calls use opaque identifiers.

• Row, field, string, probability, and schema limits defend resource boundaries.

• Experiment IDs resolve only to service-created artifacts below the configured directory.

• The service performs no arbitrary code execution, arbitrary path reads, browser fetches, or outbound messages.

• Containers run as UID/GID 10001, drop Linux capabilities, and enable no-new-privileges.

• Production deployments should terminate authenticated TLS at Archestra or a trusted gateway.

Review SECURITY.md before production use or vulnerability reporting.

Repository layout

.
├── assets/brand/          # Repository identity and hero artwork
├── data/demo/             # Reproducible anonymous dataset
├── data/artifacts/        # Runtime model pipelines (ignored)
├── docs/                  # Archestra, architecture, and demo guides
├── scripts/               # Demo-data generation
├── src/churncue/          # MCP server and deterministic business logic
├── tests/                 # Core behavior and boundary coverage
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

Engineering quality

ruff check .
ruff format --check .
pytest

The test configuration enforces at least 80% core coverage. CI runs linting, formatting, tests, package installation, and a container build on every pull request.

Documentation

Demo and screenshots

The repository includes the complete sub-three-minute demo runbook. Add the final public video URL and Archestra screenshots here after recording; no mock browser results are presented as real product output.

Known limitations

• Synthetic training data demonstrates the workflow; it is not a production churn policy.

• Threshold reason codes are operational signals, not causal or SHAP explanations.

• SQLite and local artifacts target a single service instance.

• Risk thresholds are fixed product rules and should be calibrated before production use.

• Authentication, authorization, TLS, Sheets access, and Slack delivery are external deployment responsibilities.

Roadmap

• Time-aware evaluation, probability calibration, and drift monitoring

• Managed metadata storage and object-backed model artifacts

• Tenant-aware authorization and intervention audit events

• Feedback-driven retraining and intervention outcome measurement

• Published container releases with signed provenance and SBOMs

Contributing and license

Contributions are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and use the issue templates for reproducible reports.

ChurnCue is available under the MIT License.