> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/mcp-server.md).
# 21. FullSession MCP Server
The **FullSession MCP server** lets an AI assistant — Claude Desktop, Cursor, or any MCP-compatible client — query your FullSession data directly in conversation. Instead of clicking through the app or writing API calls, you can ask *"which pages had the most rage clicks last week?"* or *"summarize what this user did before they dropped off,"* and your assistant fetches the answer from your live FullSession account.
MCP (Model Context Protocol) is an open standard for connecting AI assistants to external data sources. FullSession ships a hosted MCP endpoint, so there's nothing to install or run yourself.
***
### 21.1 What the MCP Server Is
The MCP server is a **read-only query layer** over your FullSession account. Once connected, your assistant can:
* Search and summarize **session recordings**
* Analyze **heatmaps**, element interactions, and form performance
* Read **funnel** conversion and drop-off data
* Review **Lift AI** goals and recommendations
* Pull **site-wide health overviews** and group-by analytics
It sees the same data you see in the app, scoped to the same sites — and it can't change anything.
#### How it differs from the REST API
Both let you get data out of FullSession, but they suit different jobs:
| | **REST API** ([Chapter 20](/api-developer-tools.md)) | **MCP server** (this chapter) |
| ------------ | ---------------------------------------------------- | -------------------------------------------------------- |
| **Consumer** | Your own code | An AI assistant |
| **Auth** | API token (`Bearer fus_…`) | Your FullSession login, via OAuth |
| **Surface** | One endpoint (list sessions) | **18 tools** across sessions, heatmaps, funnels, Lift AI |
| **Best for** | Pipelines, syncs, scheduled jobs | Ad-hoc investigation and analysis in conversation |
> If you want to *build* something on your data, use the REST API. If you want to *ask questions* about your data, use MCP — it exposes far more of the product.
***
### 21.2 Connecting Your AI Client
Connecting takes one URL and a browser login. There's no API key to copy or config file to hand-edit.
#### Steps
1. In your MCP client (Claude Desktop, Cursor, etc.), open its **connectors / MCP servers** settings.
2. Add the FullSession MCP endpoint:
{% code overflow="wrap" %}
```
https://app.fullsession.io/mcp
```
{% endcode %}
3. The client will prompt you to authorize. A browser window opens to the **standard FullSession login**.
4. Sign in with your normal FullSession credentials — including **SSO**, if your organization uses it ([Chapter 18](/sso.md)).
5. Approve the connection. You're returned to your client, now connected.
#### What happens behind the scenes
FullSession implements **OAuth 2.1 with Dynamic Client Registration**, so your client discovers and registers itself automatically — you never paste a client ID or secret. Login is delegated to FullSession's existing identity provider, which is why SSO works out of the box.
Once authorized, your client holds a **short-lived access token** (refreshed automatically) tied to your user account.
> **Your login, your access.** The connection authenticates *as you*. It can reach exactly the sites your account can reach — no more. If you don't have access to a site in the app, your assistant can't query it either.
#### Verifying the connection
Ask your assistant to run **`whoami`**, or simply ask *"which FullSession sites can you see?"* It should return your email and the sites available to you — a quick confirmation that auth worked and that you're pointed at the right account.
***
### 21.3 Tool Reference
The server exposes **18 tools**, grouped by area. You don't call these directly — your assistant picks the right one from your question — but knowing what exists tells you what you can ask for.
#### Identity & sites
| Tool | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`whoami`** | Returns the authenticated account and its accessible sites — useful for debugging auth |
| **`list_sites`** | Lists sites you can access, mapping each **URL → site ID** |
| **`list_segments`** | Lists your saved **segments** ([Chapter 11](/segments.md)) and the fields each filters on |
| **`get_site_overview`** | A one-call health summary: sessions, unique visitors, average duration and page count, rage/dead/error click totals, and top landing pages, countries, and devices |
> **Multi-site tip** — if your account has several sites, name the site by its **URL** in your question. Your assistant will resolve it to the right site ID via `list_sites`.
#### Sessions
| Tool | What it does |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **`search_sessions`** | Finds sessions matching filters, with frustration-signal counts and **replay links** |
| **`get_session`** | Fetches one session's metadata, signal digest, and a chronological **timeline** |
| **`aggregate_sessions`** | Groups sessions by a dimension and returns a metric per group |
| **`get_user_sessions`** | A cross-session profile for one identified user, plus their session history |
**`search_sessions`** supports a rich filter set — browser, OS, device (Desktop/Mobile/Tablet), country, city, landing page, visited URL, referrer, user ID, email, session duration, page count — plus the frustration flags **has rage clicks / dead clicks / error clicks / JS errors / network errors / abandoned form**. Results can be sorted by **start time, duration, rage clicks, or errors**, and return up to **50 sessions per page** with a cursor for the next page.
**`get_session`** returns a summary and timeline by default (the cheapest answer to *"what happened here?"*), and can optionally include raw **pages, errors, clicks, network, forms, inactivity, custom events,** and **feedback** sections when you need detail.
**`aggregate_sessions`** groups by **country, city, device, browser, OS, landing page, exit page, referrer, or user**, and reports **session count, average duration, total rage clicks, total errors,** or **sessions with errors** — optionally **compared against the previous period**, so you can ask what changed.
#### Heatmaps & clicks
| Tool | What it does |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`get_page_heatmap`** | Aggregated interaction data for a page in **clicks**, **scroll**, or **movement** mode |
| **`get_element_interactions`** | Deep-dive one element (by CSS selector or visible text) — stats plus the sessions where it was rage/dead/error clicked |
| **`get_form_analytics`** | Per-form impressions, completion, and abandonment rates |
| **`compare_pages_by_frustration`** | Ranks pages site-wide by rage/dead/error clicks, with affected-session counts |
These mirror the heatmap features in [Chapter 8](/heatmaps.md), but in queryable form — `compare_pages_by_frustration` in particular is a fast way to ask *"where is my site hurting most?"* without opening a heatmap per page.
#### Funnels
| Tool | What it does |
| ------------------------- | ------------------------------------------------------------------------------- |
| **`list_funnels`** | Funnels on a site, with step names, base segment, and processing status |
| **`get_funnel_analysis`** | Per-step users, drop-off, and median effort, plus overall conversion |
| **`get_funnel_sessions`** | Sessions that **dropped at** or **converted through** a step, with replay links |
`get_funnel_analysis` can **break down** results by country, device, browser, or OS, or **compare saved segments** against the funnel's audience — the same analysis described in [Chapter 12](/funnels.md).
#### Lift AI
| Tool | What it does |
| --------------------------------- | --------------------------------------------------------------------------------------------- |
| **`list_ai_goals`** | Your Lift AI goals, each with its latest conversion prediction |
| **`get_ai_recommendations`** | A goal's recommendations — what to fix, rationale, page, step range, and predicted lift |
| **`get_recommendation_sessions`** | The evidence sessions behind a recommendation, split by affected/unaffected and converted/not |
This makes Lift AI's findings ([Chapter 14](/lift-ai.md)) conversational — you can ask your assistant to summarize the top recommendations and explain the evidence.
***
### 21.4 What You Can Ask
The value of MCP is that you describe the question in plain language and let the assistant choose the tools. Some patterns that work well:
#### Triage and investigation
* *"Which pages had the most rage clicks in the last 7 days?"*
* *"Find sessions from mobile users in Germany that hit JavaScript errors yesterday."*
* *"Walk me through what happened in this session"* (paste a session link or ID)
* *"What did user do across her last few visits?"*
#### Analysis and trends
* *"Give me a health overview of my site for the past week."*
* *"Group last month's sessions by device and show how error rates changed vs. the previous month."*
* *"Rank my pages by dead clicks and tell me which ones affect the most sessions."*
#### Conversion work
* *"Show me the checkout funnel's drop-off by step, broken down by device."*
* *"Pull sessions where people dropped between step 2 and step 3, and summarize what they had in common."*
* *"Summarize my Lift AI recommendations and which have the highest predicted lift."*
#### Chaining is where it shines
The real advantage is multi-step work: an assistant can rank pages by frustration, pick the worst one, pull the element-level breakdown, then fetch and summarize a few affected sessions — a sequence that would take a dozen clicks in the app.
> **Tip** — results include **replay links** back into the FullSession app. When your assistant surfaces an interesting session, open the link to watch it yourself ([Chapter 6](/the-session-player.md)). Treat the assistant's summary as a fast triage layer, and the recording as the source of truth.
***
### 21.5 Limits, Safeguards & Privacy
#### Read-only by design
> **Every MCP tool is read-only.** There is no tool that creates, edits, or deletes anything — no changing settings, no deleting sessions, no modifying goals or funnels. An assistant connected to FullSession can *look*, not *touch*.
#### Time windows
| Behavior | Detail |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Maximum window** | **90 days**. A longer request is automatically clamped to the most recent 90 days, and the response says so. |
| **Default window** | Most tools default to a recent window (commonly the last 7 days; session search defaults to the last 24 hours) when you don't specify dates. |
If you want a specific period, say so in your question — *"in October"* or *"the last 30 days."*
#### Result caps and pagination
Tools return bounded pages rather than everything at once: **up to 50 sessions** per search page, **up to 50 groups** per aggregation (the remainder folded into an "other" bucket), and capped items per section when fetching a single session. Each response carries a cursor, so your assistant can page for more when it needs to.
These caps keep responses fast and readable — but be aware that a question like *"list every session this month"* will be answered in pages, not in one dump.
#### Access scope
Access is bound to **your user account**: your customer account and the sites you're permitted to see. There's currently **one permission scope** for the connection — a connected client can use **all** the read-only tools, rather than a subset you choose per tool.
#### Managing connections
> **There's no in-app screen yet for viewing or revoking connected MCP clients.** If you need a connection revoked — for example, a device you no longer use — contact FullSession support. Disconnecting the server in your AI client also stops it from being used from that machine.
Note also that the MCP endpoint is **not** covered by the REST API's rate limit ([Chapter 20, section 20.4](/api-developer-tools.md)) — the two are separate paths.
#### Privacy considerations
Because MCP hands session data to an AI assistant, apply the same care you'd apply to any tool that reads production data:
* **Your masking rules still apply.** Data excluded or masked at recording time ([Chapter 22 — Privacy, Security & Compliance](/privacy-security-compliance.md)) was never captured, so it can't be surfaced here either. Masking is your first line of defense.
* **Session data can contain personal information** — emails, names, page content, custom attributes. Be deliberate about which assistants and workspaces you connect, and follow your organization's policy on sending customer data to AI tools.
* **Connect as the right user.** Because access follows your account, connecting from a highly privileged account grants the assistant broad reach. If your organization uses custom roles ([Chapter 16](/team-account-management.md)), consider connecting from an account scoped to the sites that actually need analysis.
> **The big picture** — the FullSession MCP server turns your account into a queryable data source for AI assistants. Connect once with your normal FullSession login (SSO included), and your assistant gains **18 read-only tools** spanning sessions, heatmaps, funnels, and Lift AI — bounded by a **90-day window**, paginated results, and your own site permissions. It's the conversational counterpart to the REST API: ask questions in plain language, get answers with replay links back into the app.
***
> **Next up:** [Chapter 22 — Privacy, Security & Compliance](/privacy-security-compliance.md) covers what FullSession records and how to control it — the masking and exclusion rules that govern everything the API and MCP server can surface.
***
