MCP Server

Customerscore.io exposes a Model Context Protocol (MCP) server so AI assistants such as Claude, ChatGPT, Gemini, or Cursor can query your customer data directly — health and fit scores, churn analytics, segments, properties, and alerts — without you writing any API calls.

Endpoint

The server is stateless — there is no session handshake and no long-lived stream to keep open. It also serves OAuth discovery metadata, so clients that expect an OAuth-protected remote MCP server (like Claude.ai connectors) can connect without extra configuration.

Generate an API token

The MCP server uses the same API token as the REST API. Before connecting, generate one in the Customerscore.io application under Settings → API (opens in a new tab).

The token scopes the connection to a single account — all tool calls return data for the account the token belongs to.

Connect your client

Claude.ai

Go to Settings → Connectors → Add custom connector and fill in:

The Client ID and Client Secret fields are under Advanced settings. Click Connect afterwards — the authorization step completes automatically and the Customerscore.io tools become available in your chats.

ChatGPT

Custom MCP connectors live behind ChatGPT's developer mode:

1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
2. Back in the connector list, click Create.
3. Fill in the connector:

4. Confirm you trust the provider and click Create.
5. In a conversation, open + → More → Developer mode and enable Customerscore.

Claude Code

claude mcp add --transport http customerscore https://mcp.customerscore.io \
  --header "Authorization: Bearer your-generated-key"

Gemini CLI

gemini mcp add --transport http customerscore https://mcp.customerscore.io \
  --header "Authorization: Bearer your-generated-key"

Or add it directly to ~/.gemini/settings.json (or .gemini/settings.json in a project) — note that Gemini CLI uses httpUrl for streamable HTTP servers:

{
  "mcpServers": {
    "customerscore": {
      "httpUrl": "https://mcp.customerscore.io",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Cursor, Claude Desktop, and other clients

Add the server to your client's MCP configuration file (.mcp.json, ~/.cursor/mcp.json, claude_desktop_config.json, …):

{
  "mcpServers": {
    "customerscore": {
      "type": "http",
      "url": "https://mcp.customerscore.io",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

Restart the client after saving. The Customerscore.io tools appear in the client's tool list once the connection succeeds.

Verify the connection

List the available tools with a plain JSON-RPC request:

curl -X POST https://mcp.customerscore.io \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-generated-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A successful response contains the full tool catalog with JSON schemas for each tool's parameters.

Available tools

All tools are read-only except create_segment and create_alert, which write new segments and smart alerts to your account.

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?"
• "Create a segment for customers with a Fit Score above 70 and a Health Score below 0."
• "What are the most common cancellation reasons?"

Error responses

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