SupaStory MCP Server

Connect AI assistants to your SupaStory account. Ask about your sessions, insights, and UX issues directly in conversation.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude connect to external data sources. With the SupaStory MCP server, your AI assistant can access your session recordings, UX insights, and project data to help you analyze user behavior and fix issues faster.

Quick Start

Option A: Remote Server (Recommended)

No installation required. Just add the remote server URL to your MCP client and you're ready to go.

Prerequisites: A SupaStory account with an active subscription.

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "supastory": {
      "url": "https://app.supastory.com/api/mcp/server"
    }
  }
}

Restart Claude Desktop. On first use, you'll be prompted to sign in to your SupaStory account.

Claude Code

Add to your Claude Code settings (.claude/settings.json):

{
  "mcpServers": {
    "supastory": {
      "url": "https://app.supastory.com/api/mcp/server"
    }
  }
}

Other MCP Clients

Any MCP client that supports Streamable HTTP transport can connect to:

https://app.supastory.com/api/mcp/server

Authentication is handled automatically via MCP OAuth discovery — your client will prompt you to sign in on first use.

Option B: Local Server (Stdio)

If you prefer running the server locally, you can use the stdio transport instead.

Prerequisites:

• A SupaStory account with at least one project
• Node.js 18 or later
• Claude Desktop app

1. Log in to your SupaStory account

npx @supastory/mcp-server auth login

This opens your browser to authenticate with your SupaStory account. Your credentials are stored securely on your machine.

2. Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "supastory": {
      "command": "npx",
      "args": ["@supastory/mcp-server"]
    }
  }
}

3. Restart Claude Desktop

Quit Claude Desktop completely and reopen it. You should now see SupaStory listed as a connected tool.

What You Can Do

Analyze UX Issues

Ask Claude to review your insights and prioritize what to fix:

• "What are the most critical UX issues in my project?"
• "Show me all the errors users encountered this week"
• "Which insights are affecting conversion the most?"

Review User Sessions

Have Claude analyze specific sessions to understand user struggles:

• "Review session sess_abc123 and tell me what the user had trouble with"
• "Show me sessions where users abandoned checkout"
• "What pages are causing the most confusion?"

Aggregate & Prioritize

Roll up recurring issues across sessions to focus on what matters most:

• "Aggregate all insights for my project and show me the most frequent issues"
• "Which UX problems are affecting the most users?"
• "Group insights by severity and tell me what to fix first"

Get Code Fixes & Create PRs

Claude can generate code fixes and open pull requests directly:

• "Get the code fix context for insight ins_xyz789 and write a fix"
• "Save a code fix for the form validation issue and create a PR"
• "Help me implement the fix for the checkout bug and open a pull request"

Manage Insight Status

Keep your insights organized by updating their status:

• "Mark insight ins_abc123 as fixed"
• "Dismiss the low-severity styling issues"
• "Acknowledge the performance insights so I can come back to them later"

Project Overview

Get a quick summary of your project's health:

• "List all my SupaStory projects"
• "How many sessions were recorded in the last 7 days?"
• "Give me a summary of insights by severity"

Example Conversation

You: What are the critical issues in my checkout flow?

Claude: I'll check your SupaStory insights for critical issues related to checkout.

[Uses list_insights tool with severity=critical]

I found 3 critical issues affecting your checkout:

1. **Payment form validation error** (ins_abc123)
   - Users see confusing error messages when card number is invalid
   - Affecting 23% of checkout attempts
   - Code fix available

2. **Submit button unresponsive** (ins_def456)
   - Button appears clickable but doesn't respond on first click
   - 156 users affected this week

3. **Price calculation mismatch** (ins_ghi789)
   - Cart total doesn't match checkout total for users with discounts

Would you like me to get the code fix for any of these?

Privacy & Data Protection

PII Scrubbing

All data returned through the MCP server is automatically scrubbed of personally identifiable information (PII) before being sent to AI models. This ensures that sensitive user data from your session recordings never reaches third-party AI providers.

PII scrubbing is applied server-side to sessions, session event timelines, and insights:

| Data Type | Example Input | Scrubbed Output | |-----------|---------------|-----------------| | Names | Zach Quin | Za** Qu** | | Email addresses | [email protected] | j**[email protected] | | IP addresses | 192.168.1.100 | 192.***.*.100 | | Phone numbers | +1-555-123-4567 | ***-***-***-4567 |

In addition to pattern-based scrubbing, the server uses known identity data from session metadata (e.g., user names and emails from identify calls) to catch PII that may not match generic regex patterns. Visitor IDs and user agent strings are also stripped from session responses.

Data Handling

• Your data only — Access is scoped to projects and sessions belonging to your authenticated account
• No conversation logging — The MCP server does not log or store your conversations with AI assistants
• No telemetry — No analytics or telemetry data is collected by the MCP server
• No caching — API responses are not cached or persisted by the MCP server
• No third-party sharing — Your data is only sent to SupaStory's servers to fulfill API requests

For complete details, see our Privacy Policy.

Available Tools

These tools are available when connected to SupaStory (both remote and local modes expose the same tools):

list_projects

List all projects in your account. Returns project IDs, names, and domains.

list_sessions

List sessions for a project with optional filtering.

| Parameter | Type | Description | |-----------|------|-------------| | projectId | string | Required. The project ID | | limit | number | Max sessions to return (default: 20) | | offset | number | Offset for pagination | | status | string | Filter by: pending, processing, completed, failed |

get_session

Get detailed information about a session including page visits, event counts, and analysis status.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Required. The session ID | | includeSummary | boolean | Include the session summary in the response |

get_session_details

Get the detailed event timeline for a session. Returns significant user interactions (clicks, scrolls, page navigations, inputs, errors), console logs, and network requests with timestamps. Use this to understand exactly what a user did step by step.

| Parameter | Type | Description | |-----------|------|-------------| | sessionId | string | Required. The session ID |

list_insights

List UX insights for a project or session. On supported hosts, this tool renders an interactive insights dashboard instead of plain text (see Interactive Insights Dashboard below).

| Parameter | Type | Description | |-----------|------|-------------| | projectId | string | Project ID to list insights for | | sessionId | string | Session ID (alternative to projectId) | | type | string | Filter: usability-issue, performance, error, ux-pattern, accessibility, conversion | | severity | string | Filter: low, medium, high, critical | | status | string | Filter: open, acknowledged, fixed, dismissed | | limit | number | Max insights to return |

get_insight

Get detailed information about an insight including the description, suggestion, and code fix.

| Parameter | Type | Description | |-----------|------|-------------| | insightId | string | Required. The insight ID |

aggregate_insights

Group recurring insights by title across sessions for a project. Shows frequency, affected session count, highest severity, and status breakdown for each unique issue. Use this to prioritize fixes based on actual impact instead of reviewing duplicate insights one by one.

| Parameter | Type | Description | |-----------|------|-------------| | projectId | string | Required. The project ID | | type | string | Filter: usability-issue, performance, error, ux-pattern, accessibility, conversion | | severity | string | Filter: low, medium, high, critical | | status | string | Filter: open, acknowledged, fixed, dismissed |

get_code_fix_context

Get the full context needed to generate a code fix for a UX insight. Returns the insight details, the relevant source code file from GitHub, related files, and the framework being used.

| Parameter | Type | Description | |-----------|------|-------------| | insightId | string | Required. The insight ID |

update_insight_status

Update the status of a UX insight. Use this to mark insights as acknowledged, fixed, or dismissed.

| Parameter | Type | Description | |-----------|------|-------------| | insightId | string | Required. The insight ID | | status | string | Required. One of: open, acknowledged, fixed, dismissed |

save_code_fix

Save a generated code fix for a UX insight. After saving, you can create a pull request using create_pull_request.

| Parameter | Type | Description | |-----------|------|-------------| | insightId | string | Required. The insight ID | | files | array | Required. Array of { path, content } objects | | explanation | string | Required. Explanation of the fix | | testingNotes | string | Required. Notes on how to test the fix |

create_pull_request

Create a GitHub pull request from a saved code fix. The insight must have a code fix saved first (use save_code_fix).

| Parameter | Type | Description | |-----------|------|-------------| | insightId | string | Required. The insight ID | | title | string | Custom PR title | | body | string | Custom PR body |

Interactive Insights Dashboard (MCP Apps)

When the list_insights tool is called from a host that supports MCP Apps, an interactive HTML dashboard renders directly in the conversation instead of plain text.

Note: The interactive dashboard is available when using the local stdio server. The remote server returns plain text output for list_insights.

Supported Hosts

• Claude Desktop
• VS Code (Insiders)
• ChatGPT
• Any host implementing the @modelcontextprotocol/ext-apps extension

Dashboard Features

• Severity filtering — Filter insights by critical, high, medium, or low severity
• Summary badges — At-a-glance count of insights by severity level
• Insight cards — Clickable list showing type, severity, status, and a description preview
• Drill-down detail view — Click any insight to see the full description, suggestion, code fix (if available), element selector, and page URL
• Host theme integration — The dashboard automatically adapts to the host's light/dark theme via CSS custom properties

Graceful Fallback

If the host does not support MCP Apps, the list_insights tool returns plain text output as usual. No configuration is needed — the server detects support automatically.

Building the Dashboard

The dashboard UI is bundled as a single HTML file during the build step:

# Build the dashboard UI only
pnpm run build:app

# Build both the dashboard UI and the server
pnpm run build

The bundled file is output to dist-app/index.html and loaded by the server at startup.

CLI Commands (Local Server)

These commands are for the local stdio server only. The remote server handles authentication automatically.

# Log in to SupaStory
npx @supastory/mcp-server auth login

# Check authentication status
npx @supastory/mcp-server auth status

# Log out
npx @supastory/mcp-server auth logout

# Show help
npx @supastory/mcp-server --help

Security

Remote Server

• OAuth 2.1 — Authentication via WorkOS AuthKit with JWT tokens validated on every request
• Automatic discovery — MCP clients discover the authorization server via RFC 9728 (OAuth Protected Resource Metadata), so sign-in is handled seamlessly
• Stateless — Runs on Cloudflare Workers with no session data stored server-side
• Subscription required — Requires an active SupaStory subscription to access

Local Server

• Local storage — Credentials stored in ~/.supastory/mcp-tokens.json with restricted file permissions (600)
• Automatic refresh — Tokens are automatically refreshed when they expire
• Your data only — Access is scoped to projects and sessions belonging to your account

Troubleshooting

Remote Server

Sign-in prompt not appearing

• Verify the URL is exactly https://app.supastory.com/api/mcp/server
• Make sure your MCP client supports Streamable HTTP transport
• Try restarting your MCP client

"Active subscription required" error

Your account needs an active paid subscription. Visit app.supastory.com to subscribe.

Local Server

"Not authenticated" error

Run npx @supastory/mcp-server auth login to authenticate.

Token expired

Run npx @supastory/mcp-server auth login to re-authenticate.

Claude doesn't see SupaStory

1. Make sure you've added the config to claude_desktop_config.json
2. Restart Claude Desktop completely (quit and reopen)
3. Check that you're authenticated: npx @supastory/mcp-server auth status

"Command not found" error

Make sure Node.js 18+ is installed: node --version

Feedback

Having issues or have feature requests? Visit supastory.com or email [email protected].