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

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. Its properties parameter adds chosen custom property values to every row, so the assistant does not have to open each customer.

aggregate_property answers totals, averages, minimums, maximums and counts in one call — for example total MRR of a segment, average health score per plan, or the sum of deals across one company's contacts — over exactly the same set of customers or contacts the list tools would return, optionally grouped by a property or (for contacts) by company.

The contact tools cover the individual people at your customer companies. list_contacts lists the contacts of one company (via its customerId parameter) or searches across all of them, with filters on health score, tags, and contact properties. Contacts carry only a health score — fit score, churn risk, and MRR exist at the company level only. create_segment can also create contact segments.

Contact tools return current contacts by default. A contact becomes a former contact when it is missing from your last few contact imports or when its company churned — it says nothing about product usage. Pass isChurned: true to list_contacts, get_contact_main_stats, or aggregate_property to work with former contacts instead.

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."
• "Who are the contacts at Acme, and which of them have a declining health score?"
• "What is the total number of deals across Acme's contacts?"
• "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

Rate limits are shared with the REST API — see API Introduction.