# Fullstory Claude Plugin

**Talk to your product data.** \
Unofficial Fullstory skills for behavioral analytics, frustration discovery, and session review through the generally available Fullstory MCP server. Investigate user journeys with screenshots, console errors, and network requests.

- [Install](#quick-install)
- [What it does](#what-it-does)
- [Skills](#skills)
- [Prerequisites](#prerequisites)
- [Troubleshooting](#troubleshooting)

## Quick Install

One command in Claude Code:

```
/plugin marketplace add reatlat/fullstory-claude-plugin
/plugin install fullstory-reatlat@fullstory-marketplace
```

Also works in **Cursor** (Marketplace panel, same URL) and **VS Code Copilot** (Chat: Install Plugin from Source).

No local server. No API keys to juggle. OAuth handles auth — you sign in once and it just works.

### Hermes Agent

Hermes loads skills natively and has built-in MCP support — no plugin system needed.

```bash
# Clone the repo
git clone https://github.com/reatlat/fullstory-claude-plugin ~/fullstory-claude-plugin

# Symlink skills into Hermes
ln -s ~/fullstory-claude-plugin/skills/* ~/.hermes/skills/
```

Add the MCP server to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  fullstory:
    url: "https://api.fullstory.com/mcp/fullstory"
```

Restart Hermes. All 46 skills load automatically, and MCP tools appear as `mcp_fullstory_*`. OAuth flow triggers on first tool call.

### Claude Desktop (manual setup)

Claude Desktop doesn't support the plugin marketplace — you get the MCP tools but not the skills/agents. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fullstory": {
      "type": "http",
      "url": "https://api.fullstory.com/mcp/fullstory"
    }
  }
}
```

Config file locations: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Restart Claude Desktop after editing.

## What It Does

Fullstory records every session on your site. This plugin lets Claude *read* that data.

**Before:** Export CSV → pivot table → screenshot → Slack → someone asks "but why?" → repeat.

**After:** Type a question. Get an answer.

| You ask | Claude does |
|----------|------------|
| *"What's the top frustration on our product right now?"* | Builds a rage-click metric across all pages, surfaces the worst offenders, pulls sessions to show you exactly what users are clicking |
| *"How many users abandoned checkout last month, by device?"* | Resolves or builds a funnel metric, attaches segment, computes, returns a table with percentages |
| *"Show me sessions where enterprise users hit errors on settings"* | Builds enterprise segment, finds error sessions, reads each transcript in isolation, synthesizes patterns |
| *"Is our new onboarding flow actually reducing drop-off?"* | Trend metric comparing before/after deploy date, with statistical context |
| *"Find session #abc123 and tell me why the submit button didn't work"* | Opens session, zooms into errors and network requests, compares snapshots before/after the click, reports what broke |

It doesn't just answer "how many." It answers "why" — by reading the actual sessions behind the numbers.

**[See a real conversation →](EXAMPLE.md)** — 10 skills, one investigation, zero SQL.

## Skills

Forty-six skills ship with the plugin. Claude loads the right one automatically based on what you ask.

### Analytics & Measurement

| Skill | Trigger | What it does |
|-------|---------|-------------|
| `quick-stats` | "How many users yesterday?" | One-number answers. Build → compute → present. No analysis overhead. |
| `general-analysis` | Any quantitative question | Full workflow: classify intent, search/build, compute, validate, investigate |
| `comparisons` | A vs B questions (auto) | Picks dimensionality vs segments correctly — prevents silent wrong results |
| `funnel-doctor` | "Where are users dropping off?" | Funnel step analysis, drop-off quantification, session evidence for why |
| `weekly-digest` | "What changed this week?" | Structured report: frustrations, errors, conversion, traffic — week-over-week |
| `page-performance` | "Which page has the most errors?" | Page-level health: error rates, device breakdown, navigation patterns |
| `experiment-analyzer` | "Did the variant win?" | A/B test analysis: impact, significance assessment, segment breakdown, side effects |
| `retention-analyzer` | "Are users coming back?" | N-day retention, cohort stickiness, churn signals, engagement depth |
| `anomaly-detector` | "Did anything unusual happen?" | Proactive scan: spikes, drops, pattern breaks across all key metrics |
| `campaign-tracker` | "How did the email campaign perform?" | UTM-tagged traffic, landing page conversion, channel comparison, ROI signals |
| `feature-adoption` | "Are users using the new feature?" | Adoption funnel: awareness → trial → adoption → retention, segment breakdown |
| `benchmark-analyzer` | "What's our baseline conversion rate?" | Historical baselines, target setting, progress tracking, industry context |
| `dashboard-builder` | "Set up a product health dashboard" | Curated KPI dashboards with north star metrics, auto-saved for weekly review |
| `predictive-alerts` | "Warn me before conversion drops too low" | Trend projection, threshold breach prediction, early warning system |
| `persona-builder` | "What types of users do we have?" | Behavioral personas from real session data, data-driven user profiles |
| `lifecycle-analyzer` | "How many users are at risk of churning?" | New → active → at-risk → churned lifecycle mapping with transition rates |
| `onboarding-tutor` | "I'm new — how do I use this?" | Interactive onboarding, role-specific guides, first query walkthrough |
| `query-translator` | "How do I measure user happiness?" | Translates vague business questions into measurable Fullstory queries |
| `nps-proxy` | "What's our user satisfaction?" | Behavioral NPS alternative — satisfaction proxy from frustration/engagement signals |

### Investigation & Debugging

| Skill | Trigger | What it does |
|-------|---------|-------------|
| `frustration-hunter` | "What's frustrating users?" | Rage clicks, dead clicks, form abandonment — ranked, with session evidence |
| `error-forensics` | "What's breaking in production?" | JS errors, network failures, console exceptions — root cause from sessions |
| `session-review` | Session URL or bug report | Summary, or open → zoom → snapshot → close. Network and console evidence with visual replay |
| `session-search` | "Find sessions for user 84721" | Search by user ID, device, browser, page, custom event |
| `user-journey` | "Trace user@example.com's sessions" | Multi-session timeline, friction points, churn signals |
| `journey-builder` | "What paths do users take?" | Build/compute/update Fullstory Journeys — discover real user paths, loops, drop-offs |
| `jira-bug-reporter` | "File a bug for this session" | Auto-populated bug reports with session URL, errors, repro steps, severity |
| `customer-360` | "Show me everything about this user" | Full customer snapshot: sessions, purchases, errors, engagement trajectory |
| `form-analyzer` | "Which form field causes drop-off?" | Field-by-field abandonment, validation errors, time-to-complete, mobile forms |
| `mobile-analyzer` | "How's the mobile experience?" | Touch targets, viewport issues, responsive bugs, mobile vs desktop gap |
| `scroll-depth-analyzer` | "Are users reading to the bottom?" | Content visibility, CTA placement, where users stop scrolling per page |
| `heatmap-generator` | "What do users click on most?" | Element-level interaction density, dead click zones, rage click hotspots |
| `a11y-analyzer` | "Can keyboard users navigate this?" | Keyboard traps, focus order, missing labels, WCAG audit from real sessions |
| `api-monitor` | "Are API errors affecting users?" | Endpoint latency, error rates, API-driven UX failures, backend deploy impact |
| `session-playlist` | "Bundle these sessions for the team" | Curate annotated playlists with timestamps, narratives, and key moments |
| `changelog-detective` | "What actually changed after the deploy?" | Diff errors, frustrations, and behaviors before/after — catch undocumented changes |

### Operations & Maintenance

| Skill | Trigger | What it does |
|-------|---------|-------------|
| `deploy-radar` | "I just deployed — did anything break?" | Before/after comparison: errors, conversion, frustrations |
| `metric-auditor` | "Clean up our metrics" (auto) | Find duplicates, stale segments, misconfigured objects |
| `cohort-compass` | Cohort analysis (auto) | Build, track, reuse segments across analyses |
| `annotation-ops` | "Mark the deploy on the timeline" (auto) | Create deploy markers, experiment windows, incident tags |
| `revenue-impact` | "What does this cost us?" (auto) | Attach dollar estimates to UX issues and conversion drops |
| `segment-wizard` | "Help me build a segment for..." | Guided interactive cohort building for non-technical users |
| `privacy-auditor` | "Are we capturing PII?" | Audit session capture for PII leaks, verify masking and exclusion rules |
| `webhook-health` | "Are our webhooks delivering?" | Webhook delivery monitoring, integration health, data pipeline verification |
| `slack-reporter` | "Send this to #product-engineering" | Format findings as scannable Slack messages with evidence links and action items |
| `report-deck` | "Turn this into a board deck" | Slide structure, speaker notes, export to PPTX/PDF — evidence-linked presentations |
| `incident-responder` | "We have an incident — checkout is down" | Structured response: triage, blast radius, session evidence, status updates |

### Agents (isolated context workers)

| Agent | What it does |
|-------|-------------|
| `session-context` | Reads a single session transcript in isolation — keeps main context clean |
| `batch-session-reader` | Reads multiple sessions in parallel — 5x faster for investigation workflows |
| `session-replay` | Visual session inspector: targeted event windows and before/after snapshots in isolation |

## Prerequisites

1. **Fullstory account** with access to the [generally available MCP server](https://developer.fullstory.com/mcp/tools-reference/)
2. **StoryAI features and Model Context Protocol (MCP) enabled** by an org admin in [Settings > Account Management > StoryAI Features](https://app.fullstory.com/ui/org/settings/genai-features)
3. **Claude Code**, **Cursor**, or **VS Code Copilot**

Fullstory MCP access is included at no extra cost. Only Opportunity Lookup tools require StoryAI Premium: `get_opportunities`, `get_opportunity`, `get_sessions_for_opportunity`, and `get_managed_funnels`. Live discovery (`discover_groups`, `get_opportunity_stats`), analytics, and session review do not require Premium.

Without StoryAI and the MCP toggle enabled, the server may connect but expose no tools.

## How It Works

```
You  →  Claude Code  →  Fullstory MCP Server (api.fullstory.com)  →  Your Fullstory Data
                         ↑ OAuth, no local process
```

The plugin wires up three things:

| File | Role |
|------|------|
| `.mcp.json` | Points Claude at `https://api.fullstory.com/mcp/fullstory` |
| `skills/*/SKILL.md` | Teaches Claude *how* to think about Fullstory data — mental models, workflows, edge cases |
| `agents/*.md` | Isolated context workers for heavy lifting (session transcripts) |

The MCP server provides the tools; this plugin supplies the workflows. Tool discovery happens through the existing server URL, so no local tool implementation or endpoint change is needed.

| Tool | Use |
|------|-----|
| `review-summary` | Read a session transcript without opening server-side resources |
| `review-open` | Get the session map, initial event slice, and `client_id` |
| `review-zoom` | Read a time window with detail chosen per event kind, including console and network events |
| `review-snapshot` | Capture a screenshot, component tree, or both at a timestamp; compare two captures for before/after evidence |
| `review-close` | Free resources after every successful open, including on errors |
| `discover_groups`, `get_opportunity_stats` | Discover live frustration signals and inspect their impact without Premium |
| `build_metric`, `compute_metric`, `get_sessions` | Measure behavior and find matching session evidence |

See the [tools reference](https://developer.fullstory.com/mcp/tools-reference/) for the full catalog and [Opportunity Lookup](https://developer.fullstory.com/mcp/tools-reference/#opportunity-lookup) for Premium-only tools.

### OAuth Scopes

The OAuth flow requests read-only access to your Fullstory org. No write scopes — the plugin queries and analyzes, never modifies.

| Scope | What it grants |
|-------|----------------|
| `sessions:read` | Session transcripts, replay events, session-level search |
| `playback:read` | Session review (open, zoom, snapshot, close) |
| `playback.spec:read` | Page definitions and element specs for playback |
| `playback.page.definitions:read` | Page-level breakdowns within sessions |
| `specs.mappings:read` | Element-to-spec mappings for session analysis |
| `metrics:read` | Build and compute custom metrics |
| `metrics.funnel:read` | Funnel metrics — conversion, drop-off, step analysis |
| `metrics.page:read` | Page-level metrics — error rates, performance |
| `search:read` | Search sessions, events, and users by criteria |
| `search.metadata:read` | Search metadata — available fields, operators, values |
| `library.objects:read` | Find existing saved segments and metrics before building new ones |

All scopes are read-only. Fullstory MCP does not expose write scopes — segments and metrics created during a session return a link for manual saving in the Fullstory UI.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| **"Connected but no tools"** | Admin: enable both StoryAI features and the MCP toggle in Settings > Account Management > StoryAI Features |
| **OAuth fails** | Confirm the server URL and complete OAuth. For a protected-resource mismatch, use your regional endpoint from the [FAQ](https://developer.fullstory.com/mcp/faq/). |
| **Opportunity Lookup unavailable** | Those tools require StoryAI Premium. Use `discover_groups`, `get_opportunity_stats`, and metric-backed `get_sessions` instead. |
| **Old replay tools or missing review tools** | Refresh MCP tool discovery or reconnect. Follow `session-review` for the GA `review-*` workflow. |
| **Rate limited** | 3 req/s, 20-request burst. Space out big queries or narrow time ranges. |
| **Zero results that seem wrong** | The `general-analysis` skill auto-validates — it'll broaden filters, expand time range, and cross-check before reporting zero |

Full FAQ: [developer.fullstory.com/mcp/faq](https://developer.fullstory.com/mcp/faq/)

## License

MIT © [Alex Zappa](https://github.com/reatlat)

Skill content adapted from [fullstorydev/fullstory-skills](https://github.com/fullstorydev/fullstory-skills) (MIT).

[📝 Blog post: how we built 44 skills](BLOG.md) · [📋 MCP registry submission guide](SUBMIT.md) · [💬 Example conversation](EXAMPLE.md)

<sub>Not affiliated with Fullstory. Fullstory is a trademark of Fullstory, Inc.</sub>