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. |
Funnels
A funnel is a strictly ordered sequence of steps — events that must occur in order, within the same session, performed by the same user. These tools mirror the metric loop: build a funnel from a description, compute step-by-step conversion, then drill into the real sessions behind any step.
| Tool | Description |
|---|---|
build_funnel | Convert a natural language description of an ordered sequence of user actions into a funnel definition and persist it. Aggregation defaults to unique users. Returns a funnel_id and a direct link to the Fullstory UI. |
get_funnel | Look up one or more saved funnels by id or by name regex. Returns each funnel's funnel_id, name, step count (num_steps), and a human-readable description of its definition. Pass owned=true to restrict results to funnels you created. |
compute_funnel | Execute a saved funnel and return per-step results: the count at each step, conversion from the previous step, and conversion from step 1. Supply a funnel_id from build_funnel or get_funnel. The funnel's saved time range is always used. |
get_funnel_sessions | Get sessions scoped to a specific funnel step. Supply a funnel_id and a 0-indexed completed_step. Pass did_not_complete=true to return drop-off sessions for that step instead of completions. Each result includes a direct session replay URL. |
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. |
Agentic Session Review
These tools let you see what the user actually saw at any moment in a session: a rendered screenshot plus a component tree describing the on-page elements. Use them after get_session_events when the event transcript alone doesn't explain what happened — for example, to confirm which element was clicked, see an error state the user encountered, or pinpoint what changed on the page between two moments.
These tools are stateful. Call session_open first to load the session and get a client_id, then pass that client_id to session_view and session_diff as many times as you need. You must call session_close when you're done — open sessions hold server-side resources, so failing to close them leaks resources and may prevent further session_open calls.
The Fullstory plugin ships a built-in session review skill that guides your AI through diagnosing user-reported issues, investigating bugs, or validating UI changes from a session URL. If you have the plugin installed, invoke it with /fullstory:session-review (or /session-review depending on your platform).
| Tool | Description |
|---|---|
session_open | Open a Fullstory session for visual inspection. Pass device_id and session_id (from the session replay URL). Returns a client_id plus event summaries you can use to choose interesting timestamps. |
session_view | Render a screenshot and component tree for an open session at a given page_id and timestamp. Use this to see what the user saw at a moment of interest. Sequential calls with increasing timestamps are faster than random access. |
session_diff | Diff an open session between two timestamps on a page. Returns a screenshot at to_ts with changed regions highlighted plus a text summary of component changes. Use this to find what changed when something broke. |
session_close | Required. Close an open session and free associated resources. Always call this when you're done investigating a session — open sessions hold server-side resources, and failing to close them may block further session_open calls. |
Pages
This tool lets you reference the page definitions you've already set up in Fullstory. Use it to look up page IDs by name or pattern, 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. |
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. |