npm package: @firstdistro/mcp
Description: MCP server for customer success — monitor health scores, detect churn risks, and manage customer journeys from Claude, Cursor, and other AI tools
Author: FirstDistro
Latest version: 1.2.3

# @firstdistro/mcp

MCP server for [FirstDistro](https://firstdistro.com) — Query customer health and set up the SDK from AI assistants like Claude.

## Quick Start

### 1. Create a FirstDistro Account

Sign up at [firstdistro.com/auth/register](https://firstdistro.com/auth/register) and get your API key from **Settings → API Keys**.

### 2. Configure the MCP Server

**Option A: Interactive setup (recommended)**
```bash
npx @firstdistro/mcp init
```

**Option B: With API key directly**
```bash
npx @firstdistro/mcp init --api-key sk_live_xxxxx
```

**Option C: Claude Code CLI**
```bash
claude mcp add firstdistro -e FIRSTDISTRO_API_KEY=sk_live_xxx -- npx -y @firstdistro/mcp
```

> **Note:** Use an **API Key** (`sk_live_...` or `sk_test_...`), not an Installation Token (`fd_...`). Installation Tokens are for the browser SDK only.

### 3. Add to Claude Code

Add to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "firstdistro": {
      "command": "npx",
      "args": ["@firstdistro/mcp"]
    }
  }
}
```

### 4. Restart Claude Code

That's it! Try asking:
- "Set up FirstDistro SDK in my Next.js app"
- "Show me my FirstDistro experiences"
- "Who's stuck in onboarding?"
- "What's Acme Corp's health score?"

## Available Tools

| Tool | Description |
|------|-------------|
| `get_sdk_config` | Get your installation token and SDK setup snippets |
| `setup_sdk` | Generate files to set up FirstDistro SDK in your project |
| `list_experiences` | List all configured user journeys |
| `get_experience_stats` | Get funnel metrics for an experience |
| `get_stuck_customers` | Find customers stuck in a journey |
| `get_customer_health` | Get health score for an account |
| `list_at_risk_accounts` | List critical and at-risk customers |
| `check_events_flowing` | Verify SDK is sending events |

## SDK Setup with AI

Ask your AI assistant to set up the FirstDistro SDK:

```
User: "Add FirstDistro to my Next.js app to track user activity"

Claude: I'll set up FirstDistro in your project.

[Runs npm install @firstdistro/sdk]
[Creates app/providers.tsx with your installation token]
[Updates app/layout.tsx to use the provider]

Done! FirstDistro is now installed. Try refreshing your app
and interacting with it, then ask me "Are events flowing?"
to verify the setup.
```

### Supported Frameworks

| Framework | Status |
|-----------|--------|
| Next.js (App Router) | Full support |
| React + Vite | Full support |
| Next.js (Pages Router) | Coming soon |
| Create React App | Coming soon |

### Auth Integrations

The `setup_sdk` tool can generate user identification code for:

- **NextAuth.js** — Uses `useSession` hook
- **Clerk** — Uses `useUser` hook
- **Supabase Auth** — Uses `onAuthStateChange`
- **Custom** — Provides template with TODOs

## Example Usage

**Set up the SDK:**
```
User: "Set up FirstDistro in my React + Vite project with Clerk auth"

Claude: [Generates provider component, main.tsx updates, and Clerk user setup]
```

**Check customer health:**
```
User: "What's the health score for Acme Corp?"

Claude: Customer: Acme Corp

Health Score: 72/100
Risk Level: at-risk
Trend: declining
Last Seen: 2 hours ago
```

**Find stuck customers:**
```
User: "Who's stuck in the onboarding flow?"

Claude: Experience: User Onboarding
Stuck Alert: 15 min

Found 3 stuck customer(s):

- Acme Corp: john@acme.com (stuck 45 min)
- TechStart: sarah@techstart.io (stuck 32 min)
- DataFlow: mike@dataflow.com (stuck 18 min)
```

**Verify events are flowing:**
```
User: "Are events flowing from my app?"

Claude: ✓ Events are flowing!

Last event: 2 minutes ago
Events (24h): 1,234
Unique users (24h): 56

Top Events (24h):
  • page_view: 892
  • button_click: 234
  • form_submit: 108
```

## Configuration

Config is stored in `~/.firstdistro/config.json`:

```json
{
  "apiKey": "sk_live_xxxxx",
  "baseUrl": "https://firstdistro.com"
}
```

### Environment Variables

You can also configure via environment variables (takes priority over config file):

| Variable | Description |
|----------|-------------|
| `FIRSTDISTRO_API_KEY` | Your API key |
| `FIRSTDISTRO_BASE_URL` | API base URL (default: https://firstdistro.com) |

## Troubleshooting

### "Not configured" error
Run `npx @firstdistro/mcp init` to set up your API key, or follow the setup message which includes a link to sign up.

### "Invalid API key" error
1. Check you're using an API Key (`sk_live_...`), not an Installation Token (`fd_...`)
2. Verify the key in Settings → API Keys in your dashboard
3. Generate a new key if needed

### Tools not appearing in Claude
1. Ensure you've added the MCP server to `~/.claude/settings.json`
2. Restart Claude Code completely (not just reload)
3. Check the server runs: `npx @firstdistro/mcp`

### "Cannot reach FirstDistro API" error
1. Check your internet connection
2. Verify https://firstdistro.com is accessible
3. Check if you're behind a corporate firewall/proxy

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run locally
node bin/firstdistro-mcp.js

# Run init command
node bin/firstdistro-mcp.js init
```

## Support

- Documentation: https://firstdistro.com/documentation
- Email: support@firstdistro.com

## License

MIT