Tools Reference
The Fullstory MCP server exposes tools across four categories. All tools are available through the single server at api.fullstory.com/mcp/fullstory.
Agentic Session Review
These tools let you see what the user actually saw at any moment in a session: a rendered screenshot, an accessibility tree, or a diff between two moments. Use them after get_session_events (see Sessions) 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_screenshot, session_get_a11y_tree, 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_screenshot | Render a screenshot 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_get_a11y_tree | Get the accessibility tree for an open session at a given page_id and timestamp. Use this to inspect element structure (roles, labels, hierarchy). Sequential calls with increasing timestamps are faster than random access. |
session_diff | Diff the accessibility tree of an open session between two timestamps on a page. Returns a text summary of accessibility tree 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. |
session_viewsession_view was split into session_screenshot (rendered screenshot) and session_get_a11y_tree (accessibility tree). It is no longer functional: calling it returns a message directing you to the replacement. Use session_screenshot for visuals and session_get_a11y_tree for page structure.
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 general-analysis 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 |
|---|---|
discover_org_context | Search your org's configured objects — pages, named elements, defined events, custom events, and custom variables — in a single call. Pass multiple search terms in queries to resolve the IDs you need before building segments, metrics, funnels, or journeys. |
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. |
get_view_counts | Look up how many times saved segments or metrics have been viewed. Accepts up to 10 IDs of a single object_type (segment or metric); set the lookback with days (default 30, max 90). Use it to gauge which objects are actually popular. |
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. |
update_funnel | Refine a saved funnel's time window, aggregation, ordered steps, or conversion window — or any combination. Supply a funnel_id (from build_funnel, update_funnel, or get_funnel); pass a natural language refinement to change steps, within_seconds for the conversion window, time_range (or start_date + end_date) for the window, or aggregation. Returns a new funnel_id; the source funnel is left unchanged. |
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. |
Journeys
A journey anchors on a single event (the pivot) and shows what users did around it — the tree of paths they took before or after, with a retention-style share at each step. These tools mirror the metric and funnel loops: build a journey from a description, compute its step-by-step breakdown, then drill into the real sessions behind any path.
| Tool | Description |
|---|---|
build_journey | Convert a natural language description of an anchor event and direction into a journey definition and persist it. Resolves the pivot itself — pass the plain query (for example "what do users do after visiting the pricing page"), not a pre-looked-up ID. Returns a journey_id and a direct link to the Fullstory UI. |
get_journey | Look up one or more saved journeys by id or by name regex. Returns each journey's journey_id, name, and a plain-English journey_description (direction, pivot step, tracked interactions, audience, and time window). Pass owned=true to restrict results to journeys you created. |
compute_journey | Execute a journey and return its step-by-step breakdown: the resolved pivot, the events users reached at each step outward (each with a count and a retention-style share of the previous step), and the most common end-to-end popular_paths. Supply a journey_id from build_journey or get_journey. |
get_journey_sessions | Get sessions that passed through a journey's pivot. Supply a journey_id; optionally pass nodes (step + node_id pairs from compute_journey) to restrict results to sessions that followed a specific path. Each result includes a direct session replay URL; use page to paginate. |
update_journey | Refine a saved journey's time window, direction, attached segment, or diagram settings — or any combination. Supply a journey_id (from build_journey, update_journey, or get_journey). Returns a new journey_id; the source journey is left unchanged. |
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. For visual inspection of what the user saw at a specific moment, see Agentic Session Review.
| 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
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. |
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. |
get_managed_funnels | List the Fullstory-managed funnels for your org, each with its funnel_id and name. Use a returned funnel_id to scope get_opportunities (or discover_groups) to a specific funnel's dropouts. |