@firstdistro/mcp

MCP server for FirstDistro — Query customer health and set up the SDK from AI assistants like Claude.

Quick Start

$3

Sign up at firstdistro.com/auth/register and get your API key from Settings → API Keys.

$3

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 your ~/.claude/settings.json:

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

$3

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.
`

$3

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

$3

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"
}
`

$3

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

$3


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

$3

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

$3

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

$3

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/docs
- Issues: https://github.com/firstdistro/mcp/issues
- Email: support@firstdistro.com

License

MIT