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.
Tools that build or update segments, metrics, funnels, journeys, and dashboards save each result as a draft. A draft has its own ID that any tool accepts and a link to the Fullstory UI, but it isn't in your library until you open the link and save it. The MCP never modifies a saved object.
Agentic Session Review
These tools let you see what the user actually saw at any moment in a session: a rendered screenshot, the page's component tree, and the session's events at the level of detail you choose. Use them when the event transcript alone doesn't explain what happened. For example, confirm which element was clicked, see an error state the user ran into, or find what changed on the page between two moments.
Most of these tools are stateful. Call review-open first to load the session and get a client_id, then pass that client_id to review-zoom and review-snapshot as many times as you need. Call review-close when you're done. Open sessions hold server-side resources. review-summary returns the event transcript without opening a session, so it needs no client_id and no close.
You can open a session from a session URL (session_url), a trace (trace_id or trace_url), a device_id with a session_id, or a user (email_address or user_uid).
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 |
|---|---|
review-summary | Return a session's event transcript without opening it. Lighter than review-open. Use it when you only need to know what happened, not what the screen looked like. |
review-open | Open a session for review. Returns a map of the session (its span, flow, and counts per kind of event), a first slice of its events, and a client_id for the other tools. |
review-zoom | Re-read an open session's events with a narrower lens: a time range, and the level of detail per kind of event (for example, every error at full detail, network calls at standard). Returns the selected events as a transcript. |
review-snapshot | Capture an open session at a timestamp: a screenshot, the component tree, or both. The page is found from the timestamp, so no page id is needed. Focus on one element with component_id, or show only clickable elements with lens="interactive". To see what changed, snapshot two timestamps and compare. |
review-close | Required after review-open. Close the session and free its resources. Always call it when you're done, including after an error. |
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. Saves the segment as a draft 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 as a new draft 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. Optionally supply segment_ids to scope the metric to a segment. Saves the metric as a draft and returns a metric_id. |
build_multi_metric | Build one metric with several measures from natural language queries: up to 5 metric queries (one event measure each, assigned IDs A, B, and so on) and up to 3 formula queries that combine them (IDs f1, f2, and so on). A formula is an expression such as A/B or a description such as "the ratio of A to B", and it can reference only metric queries, so express a rate as a numerator metric, a denominator metric, and a formula. Set output_type to single_number, top_n, or trend. Set hidden=true on a query to build it without displaying it; top_n and trends grouped by a dimension allow only one visible measure. Optionally supply segment_id to scope every measure to a segment. Saves the metric as a draft and returns a metric_id, a direct link to the Fullstory UI, and each measure's id. |
update_metric | Refine an existing metric with a natural language instruction, such as "change aggregation to unique users" or "add a filter for mobile devices", or change its segment (segment_ids), time range, trend granularity (trend_granularity), or compare-to-past setting (compare_to_past), in any combination. Optionally supply output_type with a refinement to change the visualization shape. Refinements do not support ratio metrics. Saves the result as a new draft and returns a new metric_id; the source metric is left unchanged. |
compute_metric | Execute a metric definition against your data. Supply either a metric_id from build_metric or the full metric_definition JSON, which is saved as a draft. Optionally supply time_range (or start_date + end_date) to compute a different window for this call only. Returns a count, table, or trend with a link to the Fullstory UI. For a multi-metric from build_multi_metric, returns one result per measure in measures. |
get_segment | Look up one or more segments by ID or name regex. An ID lookup returns saved segments and drafts; a regex lookup returns saved segments only. Returns segment_id, name, and a human-readable description of the segment definition. |
get_metric | Look up one or more metrics by ID or name regex. An ID lookup returns saved metrics and drafts; a regex lookup returns saved metrics only. 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 save it as a draft. Aggregation defaults to unique users. Pass in_same_session=false to let steps span sessions. Returns a funnel_id and a direct link to the Fullstory UI. |
update_funnel | Refine a saved funnel's time window, aggregation, ordered steps, conversion window, or session scope — 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, aggregation, or in_same_session. Saves the result as a new draft and 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. Optionally supply segment_id to scope results, compare_to to add a prior period, or dimension to break each step down by a property. 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 save it as a draft. 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_sessions_for_journey | 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). Saves the result as a new draft and returns a new journey_id; the source journey is left unchanged. |
Dashboards
A dashboard is a page of cards with an optional segment and time-range filter applied to every card. These tools mirror the metric and funnel loops: build a dashboard from metrics and funnels you already have, compute every card in one call, then drill into any card with compute_metric or compute_funnel.
build_dashboard and update_dashboard add metric, funnel, and note cards only. Table, retention, page flow, and heatmap cards can be read, but not added.
| Tool | Description |
|---|---|
build_dashboard | Create a draft dashboard from metric, funnel, and note cards, in display order. Cards reference metrics and funnels by ID, and the tool does not change their definitions; to change a card's chart type, update its metric. Optional filters (segment_ids and a time range) apply to every card. Returns a dashboard_id and a URL to review and save the draft. |
update_dashboard | Refine a dashboard's name, description, cards, or filters, or reuse it for a new cohort. Supply a dashboard_id (from build_dashboard, update_dashboard, or get_dashboard); only the fields you pass change, and cards and filters replace the whole list. Pass segment_mapping (pairs of from and to segment IDs) to swap segments on every metric and funnel card and in the dashboard filter, and name_replacements (pairs of find and replace text) to rename cards, for example from "Control" to "Variant B". Cards that keep an old segment are listed in unswapped_cards. Copying a saved dashboard without cards carries over its metric, funnel, and note cards and lists the rest in skipped_cards. Returns a new draft dashboard_id; the source dashboard and its metrics and funnels are left unchanged. |
get_dashboard | Look up one or more dashboards by id or by name regex. Returns each dashboard's dashboard_id, name, and a direct link to the Fullstory UI; an id lookup (a saved dashboard or a draft) also returns every card, with its type and object_id, and the dashboard's filters. Pass owned=true to restrict results to dashboards you created. |
compute_dashboard | Compute a dashboard's cards and return their values, with the dashboard's filters applied. Supply a dashboard_id; pass filters to override them for this call only. Computes the first 5 cards by default (up to 15 with limit); page with offset, or pass positions for specific cards. Heatmap cards return a link instead of a value, and retention cards may not compute yet. A card that fails reports its own error while the rest still compute. |
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 segment or a draft). Each result includes a direct session replay URL. For a metric built with build_multi_metric, use get_multi_metric_sessions instead. |
get_multi_metric_sessions | Get sessions matching one or more measures of a multi-metric. Supply a metric_id (from build_multi_metric) and, optionally, measure_ids (the measure IDs returned by build_multi_metric or compute_metric). Sessions matching any of the given measures are returned, and a formula measure is expanded to the event measures it references. Omit measure_ids to search across every measure. Results are one row per user; set include_matching_sessions=true to expand each user on the page into all of their matching sessions. Page with limit (default 10, maximum 50) and offset. 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. Optionally supply start_time and end_time to limit the transcript to a window around a specific moment. |
Pages
Only available for customers with StoryAI Premium SKU.
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; 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 with scope: any combination of page_ids, domains (URL hostnames), app_names (mobile apps), and url_paths, plus either a segment_id (saved segment) or a 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. |
get_sessions_for_opportunity | Get real sessions where a specific frustration signal was observed. |
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). Set exclude_bots to omit bot opportunities; each result includes is_bot when the majority of contributing sessions show at least 1 bot signal. |
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. The result includes is_bot when the majority of contributing sessions show at least 1 bot signal. |
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. |