Claude code setup

Connect FirstDistro to Claude Code or Claude Desktop to query customer health, check events, and manage experiences from your AI assistant.

Prerequisites

• Claude Code CLI or Claude Desktop installed
• FirstDistro API key — Get one from Settings

Claude code (cli)

Configure mcp

Run this command:

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

This saves your config to ~/.firstdistro/config.json.

Add to claude code settings

Open your Claude Code settings file:

• macOS/Linux: ~/.claude/settings.json
• Windows: %USERPROFILE%\.claude\settings.json

Add the MCP server:

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

Restart and verify

1. Quit and reopen Claude Code
2. Ask Claude: "What FirstDistro tools do you have access to?"
3. You should see tools like list_experiences, check_events_flowing, etc.

Claude desktop

Configure firstdistro

Run this command in your terminal:

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

Add to desktop config

Open the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the MCP server:

{
  "mcpServers": {
    "firstdistro": {
      "command": "npx",
      "args": ["-y", "@firstdistro/mcp"]
    }
  }
}

Restart desktop and verify

1. Quit and reopen Claude Desktop completely (not just close the window)
2. Ask Claude: "What FirstDistro tools do you have access to?"

Alternative: environment variable

Instead of running init, you can set the API key as an environment variable:

{
  "mcpServers": {
    "firstdistro": {
      "command": "npx",
      "args": ["-y", "@firstdistro/mcp"],
      "env": {
        "FIRSTDISTRO_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

This is useful for CI/CD or when you don't want to run init.

Troubleshooting

Claude doesn't see the tools

1. Check the config file path is correct
2. Verify your API key starts with sk_live_ or sk_test_
3. Restart Claude completely (not just close window)
4. Check Claude's developer console for errors

"api key invalid" errors

1. Go to Dashboard → Settings → API Keys
2. Create a new API key (not Installation Token)
3. Run npx @firstdistro/mcp init --api-key NEW_KEY
4. Restart Claude

"authentication failed" errors

• Make sure you're using an API key (sk_live_...), not an Installation Token (fd_...)
• Installation Tokens are for the browser SDK, not MCP

Tools return "not configured"

Run the init command again:

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

Then restart Claude.

Next steps

• Tools Reference — See all available tools
• MCP Overview — Learn what MCP can do