@flusterduck/mcp-server

Local stdio MCP server for Flusterduck. Exposes your site's confusion scores, UX issues, alerts, deploys, session timelines, recommendations, and raw data to AI assistants over the Model Context Protocol.

Run it on your machine to connect Claude Desktop (or any MCP-compatible client) to your Flusterduck data without opening a public endpoint.

Run it

No install required:

npx -y @flusterduck/mcp-server

Or install the flusterduck-mcp binary globally:

npm install -g @flusterduck/mcp-server
flusterduck-mcp

The server communicates over stdio and is meant to be launched by an MCP client rather than used interactively.

Configuration

Configuration is read from environment variables:

| Variable | Required | Description | |---|---|---| | FLUSTERDUCK_MCP_KEY | yes | Your Flusterduck MCP key (fd_mcp_...), created in the dashboard under Settings > API Keys. FLUSTERDUCK_API_KEY is accepted as an alias. | | FLUSTERDUCK_SITE_ID | no | A site UUID. Site-scoped keys (the dashboard default) already know their site, so this is only needed for org-scoped keys, to pick which site to read. | | FLUSTERDUCK_ORG_ID | no | Pins org-level reads (audit log, degradation, webhook deliveries) to a specific org. Normally unnecessary: the key's own org is used automatically. | | FLUSTERDUCK_API_URL | no | Override the Flusterduck query API base URL. Defaults to the hosted Flusterduck API. |

Use an MCP key (fd_mcp_) or a secret key (fd_sec_). Publishable keys (fd_pub_) are browser-only and will not authenticate against the query API. Write tools (issue/alert updates, alert-rule and annotation management) require a key with manage:write scope.

Prefer zero configuration? The hosted MCP server at https://mcp.flusterduck.com/mcp needs no keys at all: you sign in with your Flusterduck account on first use.

Claude Desktop configuration

Add to your claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "flusterduck": {
      "command": "npx",
      "args": ["-y", "@flusterduck/mcp-server"],
      "env": {
        "FLUSTERDUCK_MCP_KEY": "fd_mcp_..."
      }
    }
  }
}

The key comes from the dashboard (Settings > API Keys) and is scoped to your current site when you create it, so one env var is the whole setup. Full setup guide for Claude Code, Cursor, Windsurf, and VS Code: https://docs.flusterduck.com/mcp

Available tools

| Tool | Description | |---|---| | whoami | What this key is: org/site scope and granted scopes | | get_site_context | Full MCP snapshot for the configured site | | get_scores | Current page confusion scores | | get_page | Score history, issues, alerts, and elements for one page | | get_elements | Element-level friction summaries | | get_issues | UX issues, newest first, pageable; filter by status (open, triaged, in_progress, verified, resolved, ignored, regressed) | | get_issue | Single issue with evidence, sessions, and verification history | | get_alerts | Alerts, newest first, pageable; filter by status (fired, acknowledged, investigating, resolved) | | list_alert_rules | Configured alert rules | | get_session_detail | Full event timeline for a session | | get_flows | Page-to-page flow edges from recent sessions | | get_trends | Score history over 1-90 days | | get_conversion_insights | Confused-vs-calm conversion analysis: cohort deltas, per-page and per-source breakdowns, ranked insights | | get_deploys | Deploys with confusion_before / confusion_after | | compare_pages | Side-by-side confusion comparison for two pages | | get_recommendations | Prioritized fix recommendations | | get_revenue_impact | Revenue impact estimates | | get_heuristics | Full friction heuristic catalog | | diagnose_journey_friction | High-friction path edges from recent sessions | | query_raw_rows | Raw rows from allowlisted tables | | explore | Deterministic typed query engine over session data: AND-ed filters, list sessions or measure a metric | | download_events_csv | CSV export of raw events | | get_audit_log | Organization audit log (needs an org-scoped key) | | get_degradation | Active backend degradation events (works with site-scoped keys too) | | get_webhook_deliveries | Outbound webhook delivery history (needs an org-scoped key) | | list_docs | List every Flusterduck documentation page with slug, title, and group | | search_docs | Keyword search over the bundled documentation | | get_doc | Full markdown of one documentation page by slug |

Write tools (require manage:write scope): update_issue, update_alert, add_annotation, create_alert_rule, update_alert_rule, delete_alert_rule, and send_feedback (send suggestions or bug reports about Flusterduck itself to the team).

Resources

| URI | Description | |---|---| | flusterduck://site/context | Current site context snapshot | | flusterduck://page/{path} | Detailed context for a specific page path |

Prompts

diagnose_page, triage_open_issues, post_deploy_check, investigate_session, weekly_summary: guided multi-step workflows for common UX investigations.

Programmatic usage

import { createFlusterduckMCPServer } from '@flusterduck/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createFlusterduckMCPServer({
  apiKey: process.env.FLUSTERDUCK_MCP_KEY!,
  // Optional for site-scoped keys; required for org-scoped keys.
  siteId: process.env.FLUSTERDUCK_SITE_ID,
  baseUrl: process.env.FLUSTERDUCK_API_URL ?? 'https://api.flusterduck.com/v1',
});

const transport = new StdioServerTransport();
await server.connect(transport);

(c) Flusterduck. Proprietary. All rights reserved.