@firstdistro/mcp

MCP server for FirstDistro — 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 and get your API key from Settings → API Keys.

2. Configure the MCP Server

Option A: Interactive setup (recommended)

npx @firstdistro/mcp init

Option B: With API key directly

npx @firstdistro/mcp init --api-key sk_live_xxxxx

Option C: Claude Code CLI

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:

{
  "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: [email protected] (stuck 45 min)
- TechStart: [email protected] (stuck 32 min)
- DataFlow: [email protected] (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:

{
  "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

# 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: [email protected]

License

MIT