MCP Server
Customerscore.io exposes a Model Context Protocol (MCP) server so AI assistants such as Claude, ChatGPT, Gemini, or Cursor can work with your customer data directly — health and fit scores, churn analytics, segments, properties, and alerts — without you writing any API calls.
Ask about customer health, churn trends, upcoming renewals, or your most at-risk accounts, and the assistant answers using live data from your account.
Setup instructions live in the per-client guides: Claude, ChatGPT, Gemini, and other MCP clients.
Available tools
| Category | Tools |
|---|---|
| Customers | list_customers, get_customer_detail, get_customer_notes, get_customer_main_stats, get_customer_ai_summary |
| Scoring & churn | get_scoring_history, get_churn_analytics, get_lost_mrr |
| Analytics & insights | get_insights, get_mrr_trend_by_health, get_statistics_overview |
| Segments | list_segments, create_segment |
| Properties & tags | list_properties, get_property_values, list_tags |
| Alerts | list_alerts, create_alert |
All tools are read-only except create_segment and create_alert, which write new segments and smart alerts to your account. Both only add new items — the server can never edit or delete existing data.
list_customers is the workhorse: it covers free-text lookup by name or email (via its search parameter), cohort filters (churn risk, health score, tags, custom properties), churned customers, upcoming renewals, and trending customers via health-score-change sorting.
Most customer tools work with the internal numeric customer ID. If you only
know a name or email, the assistant resolves it with the search parameter of
list_customers first.
Example prompts
Once connected, you can ask your assistant things like:
- "Which customers are at risk of churning in the next 30 days?"
- "Show me the customers with the biggest health score drop this month."
- "How much MRR did we lose to churn in the last quarter, month by month?"
- "List customers renewing in the next 30 days with a health score under 50."
- "Create a segment for customers with a Fit Score above 70 and a Health Score below 0."
- "Set up an alert that emails me when any customer's churn risk hits 4 or more."
Security & data handling
- All traffic is HTTPS.
- Claude connections use OAuth 2.1 with PKCE — access tokens are short-lived and scoped to a single account, and you can revoke them at any time by removing the connector.
- Token connections are scoped to the account the API token belongs to.
- The server only reads and writes data inside your Customerscore.io account; it never calls external services.
Error responses
| Status | Meaning |
|---|---|
401 | Missing or invalid credentials (token clients) or expired OAuth access token |
403 | Invalid API token |
406 | Content-Type is not application/json |
490 | Scoring is not configured for the account — finish setup in the application |
491 | Account is blocked |
Rate limits are shared with the REST API — see API Introduction.