MCP tools reference

Complete reference for all tools available in the FirstDistro MCP server.

List_experiences

List all user journeys/funnels you're tracking (called "experiences" in FirstDistro).

Parameters: None

Example prompt:

"Show me my FirstDistro experiences"

Example response:

Found 3 experience(s):

- Onboarding Flow (active)
- Checkout Funnel (active)
- Feature Adoption (pending)

Use cases:

• See what user journeys you're tracking
• Verify experiences are configured correctly
• Find experience IDs for other tools

Check_events_flowing

Verify that your SDK is properly sending events to FirstDistro.

Parameters: None

Example prompt:

"Are my FirstDistro events flowing?"

Example response:

✓ Events are flowing!

Last event: 2 minutes ago
Events (24h): 1,247
Unique users (24h): 89

Top Events (24h):
  • $pageview: 523
  • feature_used: 312
  • user_logged_in: 89

Use cases:

• Verify SDK installation after setup
• Debug why events aren't appearing
• Check event volume and activity

Get_customer_health

Get health score and details for a specific customer account.

Parameters:

Example prompt:

"What's the health score for Acme Corp?"

Example response:

Customer: Acme Corp

Health Score: 72/100
Risk Level: at-risk
Trend: declining
Last Seen: 3 days ago

Use cases:

• Check on a specific customer before a call
• Investigate why a customer might be at risk
• Get quick health overview without opening dashboard

Get_experience_stats

Get funnel statistics for a user journey: how many started, completed, conversion rate, and average time.

Parameters:

Example prompt:

"What's the completion rate for the onboarding flow?"

Example response:

Experience: Onboarding Flow
Time Range: 7d

Started: 156
Completed: 89
Completion Rate: 57%
Avg Time to Complete: 12m

Use cases:

• Check funnel performance
• Compare conversion rates across time periods
• Identify bottleneck flows

Get_stuck_customers

Find customers who started a journey but stopped progressing. Useful for identifying users who need help.

Parameters:

Example prompt:

"Who's stuck in the checkout funnel?"

Example response:

Experience: Checkout Funnel
Stuck Alert: 30 min

Found 5 stuck customer(s):

- Acme Corp: john@acme.com (stuck 45 min)
- Beta Inc: sarah@beta.io (stuck 38 min)
- Gamma LLC: mike@gamma.co (stuck 32 min)

Use cases:

• Find users who need proactive support
• Identify friction points in onboarding
• Enable real-time intervention for stuck users

List_at_risk_accounts

List customer accounts with at-risk or critical health scores.

Parameters:

Example prompt:

"Which customers are at risk of churning?"

Example response:

At-Risk Accounts Summary:
• Critical: 3
• At-Risk: 8
• Healthy: 42

- Acme Corp: Score 25/100 (critical) 📉
- Beta Inc: Score 38/100 (at-risk)
- Gamma LLC: Score 42/100 (at-risk) 📈
...

Use cases:

• Daily check on account health
• Prioritize customer success outreach
• Identify churn risk before it's too late

Get_sdk_config

Get your FirstDistro installation token and SDK configuration snippets.

Parameters: None

Example prompt:

"Get my FirstDistro SDK config"

Example response:

FirstDistro SDK Configuration

Installation Token: fd_abc123...
Vendor: my-company

Quick Start:
1. Install: npm install @firstdistro/sdk

2. Add the provider to your app:
   import { FirstDistroProvider } from '@firstdistro/sdk/react'
   <FirstDistroProvider token="fd_abc123...">{children}</FirstDistroProvider>

3. Set up identity after login (userEmail required):
   import { useFirstDistroSetup } from '@firstdistro/sdk/react'
   useFirstDistroSetup({ userId: user.id, userEmail: user.email })

4. Track custom events:
   FirstDistro.track('event_name', { property: 'value' })

Use cases:

• Quick reference for installation token
• Copy-paste setup code
• Share setup instructions with teammates

Get_server_event_template

Return the vertical server-event catalog (milestones, activity, risk) for server-side track() wiring. Event names are fixed. Do not invent custom names.

Parameters:

Example prompt:

"Get my server event template for Fintech"

Example response:

Server event catalog (Fintech)
Resolved from: query

Milestones:
- kyc_approved
- bank_account_linked
- first_deposit_completed
- first_payment_sent
- limits_increased

Recommended activity:
- subscription_started
- integration_sync_completed
- first_production_api_call

Recommended risk:
- payment_failed
- kyc_rejected

Snippet hints:
- Env: FIRSTDISTRO_API_KEY
- Import: @firstdistro/sdk/server

Event names are fixed. Do not invent custom names. Use Event settings to add custom milestones.

Use cases:

• Wire server track() calls to catalog event names
• Pick Fintech, B2B SaaS, or Gaming milestone lists without guessing names
• Confirm env var and import path for @firstdistro/sdk/server

Setup_server_tracking

Generate a Node server-tracking snippet (createServer, FIRSTDISTRO_API_KEY, flush) plus a catalog event example. Put the sk_* key in .env, not in source files.

Parameters:

Example prompt:

"Set up server tracking for Fintech"

Use cases:

• Wire @firstdistro/sdk/server in a webhook or job
• Copy the env var name and flush note
• Get a catalog event example instead of inventing names

Check_server_events_flowing

Verify that server-originated events (properties.source=server) are arriving. Optionally check expected catalog names.

Parameters:

Example prompt:

"Check if server events are flowing for kyc_approved and payment_failed"

Use cases:

• Confirm ingest after wiring track()
• See which expected catalog names are still missing

Setup_sdk

Generate all files and commands needed to set up the FirstDistro SDK in your project. Returns framework-specific setup files.

Parameters:

Example prompt:

"Add FirstDistro SDK to my Next.js project"

Example response:

# Firstdistro sdk setup for next.js (app router)

## Installation token
`fd_abc123...`

## Commands to run
- `npm install @firstdistro/sdk`, Install the SDK

## Files to create or modify

### App/providers.tsx (create)
Provider component to wrap your app

\`\`\`tsx
'use client'
import { FirstDistroProvider } from '@firstdistro/sdk/react'
...
\`\`\`

### App/layout.tsx (modify)
Wrap children with the provider
...

## Verification
After setup, use the `check_events_flowing` tool to verify.

Use cases:

• Quick SDK setup without leaving your IDE
• Get framework-specific code snippets
• Auth-aware user identification setup

Tips for using mcp tools

Natural language works

You don't need to remember exact tool names. Just ask naturally:

• "Are events coming through?" → check_events_flowing
• "Show at-risk customers" → list_at_risk_accounts
• "How's Acme Corp doing?" → get_customer_health
• "Set up FirstDistro in this project" → setup_sdk

Combine with context

MCP tools work best when combined with your codebase:

"Set up FirstDistro in this Next.js project and use my existing auth from lib/auth.ts"

Follow-up questions

Claude can remember context:

"Which customers are at risk?" "Tell me more about the first one" "What might be causing their declining health?"