Tools Reference
The Fullstory MCP server exposes tools across three categories. All tools are available through the single server at api.fullstory.com/mcp/fullstory.
Analytics
These tools let you ask quantitative questions about your data in plain language. Describe a user behavior or cohort and Fullstory translates it into a segment or metric definition. The results can be verified in Fullstory's UI.
The Fullstory plugin ships a built-in analytics skill that guides your AI through a structured workflow: classify the question, search for existing segments and metrics before building new ones, compute results, validate them, then investigate sessions for the "why." If you have the plugin installed, invoke it with /fullstory:general-analysis (or /general-analysis depending on your platform).
| Tool | Description |
|---|---|
build_segment | Convert a natural language description into a Fullstory segment definition. Persists the segment and returns a segment_id and a direct link to the Fullstory UI. |
update_segment | Structurally refine an existing segment definition using a natural language instruction, such as "add iOS users only" or "remove the checkout filter". Saves the updated segment and returns a new segment_id. |
build_metric | Convert a natural language query into a metric definition. Supports single_number, top_n, and trend output types. |
update_metric | Structurally refine an existing metric definition using a natural language instruction, such as "change aggregation to unique users" or "add a filter for mobile devices". Returns a new metric_id and updated definition. Optionally supply output_type to change the visualization shape. Does not support ratio metrics. |
compute_metric | Execute a metric definition against your data, optionally scoped to a segment and time range. Supply either a metric_id from build_metric or the full metric_definition JSON. Returns a count, table, or trend with a link to the Fullstory UI. |
get_segment | Look up one or more saved segments by ID or name regex. Returns segment_id, name, and a human-readable description of the segment definition. |
get_metric | Look up one or more saved metrics by ID or name regex. Returns metric_id, name, and a human-readable description of the metric definition. |
Sessions
These tools take you from aggregate numbers to real user evidence. Pass any segment or metric through these tools to get a list of matching sessions, then read individual sessions with get_session_events. This is how you answer "what actually happened" after a metric or segment tells you something interesting.
| Tool | Description |
|---|---|
get_sessions | Get sessions matching a metric or segment. Provide exactly one of metric_id (sessions where a metric's events occurred) or segment_id (sessions matching a saved or unnamed segment). Each result includes a direct session replay URL. |
get_session_events | Fetch a complete, chronological transcript of all events in a session: clicks, navigations, errors, network requests, and more. |
Pages & Funnels
These tools let you reference the page definitions and funnel definitions you've already set up in Fullstory. Use them to look up page IDs by name or pattern, or to retrieve your managed funnels, so you can scope other tools to a specific area of your product.
| Tool | Description |
|---|---|
get_pages | List page definitions (both user-defined and automatically detected). Optionally provide a regex to filter pages by name or friendly ID; if omitted, all pages are returned. |
get_managed_funnels | List all funnels that are being monitored with StoryAI Opportunities. Use the returned funnel_id with get_opportunities or discover_groups to scope queries to a specific funnel. |
StoryAI Opportunities
Tools for discovering and analyzing where users struggle in your product.
Opportunity Discovery
These tools query your data in real time to surface frustration signals, errors, and regressions you may not know about yet. Scan broadly across pages, funnels, segments, or your entire application, then drill into a specific group for deeper analysis.
| Tool | Description |
|---|---|
discover_groups | Find the top frustration signals across your product data. With no scope set, queries your entire org. Scope to a subset by providing exactly one of: page_id, domain (URL hostname), app_name (mobile app), segment_id (saved segment), or funnel_id (funnel dropouts). Optionally compare to a prior period (compare_to_previous=true) to surface regressions. |
get_opportunity_stats | Get live-computed stats for a specific frustration signal: affected users, page/domain/device breakdowns, and rate of change. |
classify_opportunity | Triage a frustration signal by sampling real sessions: session position, time-to-event, noise assessment, angry-highlight detection, and third-party attribution. |
Opportunity Lookup
Only available for customers with StoryAI Premium SKU.
These tools return pre-ranked results from Fullstory's ongoing monitoring as part of StoryAI Opportunities. Use them when you want to see what Fullstory has already flagged. Results can be scoped by segment, time range, page, or funnel.
| Tool | Description |
|---|---|
get_opportunities | Get pre-ranked StoryAI Opportunities for the org. Optionally scope by providing exactly one of: segment_id, page_id, or funnel_id. Control the lookback window with time_range (24h, 7d, 14d, 30d). |
get_opportunity | Get the full stored record for a specific StoryAI Opportunity. Provide either an instance_id (short alphanumeric identifier) or a default_metric_id + group_id pair. |
get_sessions_for_opportunity | Get real sessions where a specific frustration signal was observed. |