MCP Server

The UserSesh MCP server lets AI coding tools read your analytics data, find UX issues, and debug user sessions — all from within your IDE.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI coding tools connect to external data sources. With the UserSesh MCP server, your AI agent can:

See what UX issues users are hitting and fix them
Find JavaScript errors with full stack traces
Identify rage clicks and broken UI elements
Read real-time analytics (who's on your app right now)
Debug specific user sessions step-by-step
Find unused pages and dead features
Get an overall UX health score with recommendations

Setup

You need an API key from your dashboard: Settings → API Keys.

Cursor

Save this to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "usersesh": {
      "command": "npx",
      "args": ["-y", "usersesh-mcp"],
      "env": {
        "USERSESH_API_KEY": "YOUR_KEY_HERE",
        "USERSESH_URL": "https://usersesh.com"
      }
    }
  }
}

Claude Code

Run this in your terminal:

claude mcp add usersesh -- npx -y usersesh-mcp

Then set the environment variables USERSESH_API_KEY and USERSESH_URL=https://usersesh.com in your shell profile or project config.

Windsurf

Add this to your Windsurf MCP configuration file:

{
  "mcpServers": {
    "usersesh": {
      "command": "npx",
      "args": ["-y", "usersesh-mcp"],
      "env": {
        "USERSESH_API_KEY": "YOUR_KEY_HERE",
        "USERSESH_URL": "https://usersesh.com"
      }
    }
  }
}

Any MCP-compatible client

The MCP server runs via npx. The command is:

npx -y usersesh-mcp

Required env: USERSESH_API_KEY. Optional: USERSESH_URL (defaults to https://usersesh.com).

Available Tools

The MCP server exposes 9 tools that your AI agent can call. Here's what each one does and when to use it.

get_top_issues

Get a prioritized list of UX issues ranked by severity and user impact. This is the best starting point to understand what needs attention.

Param	Type	Description
period	string	`"24h"` \| `"7d"` \| `"30d"` \| `"90d"` (default: "7d")

Returns: Issue title, type, severity score, page, affected sessions count, and AI-generated context for each issue.

get_errors

Get JavaScript errors users are encountering, with stack traces and frequency. Use this to find and fix bugs.

Param	Type	Description
period	string	Time period (default: "7d")
page	string	Optional URL path filter (e.g. "/dashboard")

Returns: Error message, file:line, type, occurrence count, first/last seen timestamps.

get_rage_clicks

Get UI elements users are frustration-clicking on. Indicates broken buttons, unresponsive elements, or confusing UX.

Param	Type	Description
period	string	Time period (default: "7d")
page	string	Optional URL path filter

Returns: Element selector, tag, text content, click count, affected sessions, pages.

get_analytics_summary

Get high-level analytics: visitors, sessions, page views, bounce rate, top pages, referrers, and device breakdown.

Param	Type	Description
period	string	Time period (default: "7d")

Returns: Visitors, sessions, page views, bounce rate, avg duration, top pages, referrers, device/browser/country breakdown.

get_realtime

Get real-time data: how many users are on your app right now and what they're doing. No parameters.

Returns: Active visitors/sessions, visitors in last 30min, current rate, device breakdown, top active pages, visitor countries.

get_session_detail

Get the full story of a specific user session. Useful for debugging a reported issue.

Param	Type	Description
session_id	string	The session ID to look up (required)

Returns: Visitor info, pages visited with timestamps, events, errors, rage clicks.

get_dead_features

Find pages and features nobody is using. Helps identify dead code or features to remove or improve.

Param	Type	Description
period	string	Time period (default: "30d")
min_views	number	Minimum views threshold (default: 10)

Returns: Unvisited pages, low-scroll pages (less than 15% avg scroll depth).

get_vibe_score

Get the overall Vibe Score — a 0-100 health score for user experience, broken down by component. Includes actionable recommendations.

Param	Type	Description
period	string	Time period (default: "7d")

Returns: Overall score + letter grade, component scores (error rate, rage clicks, bounce rate, engagement, session duration, mobile parity), trend direction, top recommendations.

get_page_performance

Get per-page engagement metrics. Helps identify which specific pages need work.

Param	Type	Description
period	string	Time period (default: "7d")
sort_by	string	`"bounce_rate"` \| `"views"` \| `"avg_time"`

Returns: Per-page bounce rate, scroll depth, time on page, mobile vs desktop breakdown.

Example Prompts

Once connected, you can ask your AI agent things like:

"What are the top UX issues this week? Fix the most critical one."

"Show me all JavaScript errors on the /dashboard page and fix them."

"What's the vibe score? What should I work on to improve it?"

"Are there any rage clicks happening? Make those buttons work better."

"Which pages have the highest bounce rate? Let's improve them."

"Find unused pages I can clean up or remove."

"How many users are on the app right now?"

"Debug session abc-123 — what went wrong?"

Next steps

JavaScript SDK — Install the tracker and configure it
Events & Identification — Custom events and user identification
Conversion Tracking — Track revenue for ad ROAS