@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 <API_KEY>

Init writes ~/.firstdistro/config.json and merges a firstdistro stdio server into Cursor (~/.cursor/mcp.json), Claude Code (~/.claude/settings.json), and Claude Desktop. Use --client cursor|claude-code|claude-desktop|all to override. Default: clients that already exist on disk, or all if none do.

Option C: Claude Code CLI

claude mcp add firstdistro -- 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. Never pass an example key; use <API_KEY> from Settings.

3. Restart your editor

Restart Cursor, Claude Code, or Claude Desktop. That is the only step init cannot do.

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?"
• "Which accounts need attention right now?"
• "Search for Acme Corp"

Remote HTTP (optional)

The same tools are also available at https://firstdistro.com/mcp for clients that speak Streamable HTTP. Send your server API key as X-API-Key.

For Cursor and Claude Code in a local project, keep using npx @firstdistro/mcp as in Quick Start.

Available Tools

19 tools (v1.5.0). All require a server API key (sk_live_... / sk_test_...).

SDK & setup

| 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 | | get_server_event_template | Return vertical server-event catalog for server-side track() wiring | | setup_server_tracking | Generate a Node server-tracking snippet with FIRSTDISTRO_API_KEY | | check_server_events_flowing | Verify server-originated events are arriving | | check_events_flowing | Verify SDK is sending events |

Experiences

| Tool | Description | |------|-------------| | list_experiences | List all configured user journeys | | create_experience | Create a new experience to track a customer journey | | get_experience_stats | Get funnel metrics for an experience | | get_stuck_customers | Find customers stuck in a journey |

Customer success

| Tool | Description | |------|-------------| | get_customer_health | Get health score for an account | | list_at_risk_accounts | List critical and at-risk customers | | get_priorities | List accounts that need attention, sorted by urgency | | list_upcoming_renewals | Summarize the renewal pipeline by bucket | | get_portfolio_pulse | Snapshot of healthy/at-risk/critical account counts |

Account intelligence & CRM

| Tool | Description | |------|-------------| | get_churn_risk | Get the deterministic churn-risk baseline for an account | | get_customer_contacts | List the contacts recorded for a customer account | | get_integration_status | Check which integrations (CRM, Slack, SDK) are connected | | search_customers | Search customer accounts and users by name or email |

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 scaffold via setup_sdk | | React + Vite | Full scaffold via setup_sdk | | Vanilla JavaScript (script tag) | Full scaffold via setup_sdk — no npm required | | Next.js (Pages Router) | Manual README via setup_sdk — prefer App Router or script tag | | Create React App | Manual README via setup_sdk — prefer Vite or script tag |

Auth Integrations

The setup_sdk authPattern option applies to React scaffolds (nextjs-app, react-vite) only. Vanilla uses a generic script-tag setup() snippet regardless of auth library.

• 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": "<API_KEY>",
  "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

Changelog

1.5.0 (2026-08-30)

Init writes client configs (FIR-702)

• npx @firstdistro/mcp init --api-key <API_KEY> still saves ~/.firstdistro/config.json
• Init also merges a firstdistro stdio server into Cursor, Claude Code, and Claude Desktop configs
• --client cursor|claude-code|claude-desktop|all overrides which files to write
• Default: clients that already exist on disk, or all if none do
• Restart the editor after init. That is the only step init cannot do.

1.4.0 (2026-08-13)

Server event catalog (FIR-641 Slice 1)

• get_server_event_template: vertical milestone, activity, and risk event names for server-side track() wiring (B2B SaaS, Fintech, Gaming)
• setup_server_tracking: Node createServer snippet + FIRSTDISTRO_API_KEY (never embeds sk_*)
• check_server_events_flowing: verify properties.source=server ingest

1.3.0 (2026-06-06)

Customer success & CRM tools (7 new)

• get_priorities — "Needs Your Attention" queue
• list_upcoming_renewals — renewal pipeline buckets
• get_portfolio_pulse — portfolio health snapshot
• get_churn_risk — deterministic churn baseline per account
• get_customer_contacts — account contacts list
• get_integration_status — CRM / Slack / SDK connection status
• search_customers — search accounts and users by name or email

setup_sdk framework router

• Full scaffold for vanilla (script tag + setup(), no npm)
• Honest manual README for Next.js Pages Router and Create React App (no more "coming soon")
• authPattern documented as React-scaffold-only; vanilla ignores auth-specific branches

1.2.4

• Nine core tools: experiences, health, at-risk, SDK setup, event verification

Support

• Documentation: https://firstdistro.com/documentation
• Email: [email protected]

License

MIT