AgentFirstStack

Microsoft Clarity MCP: what it returns, and replay built for agents

Microsoft's Clarity MCP server lets an AI client query dashboard metrics and list session recordings from a Clarity project that a person created, using that project's API token. AgentFirstStack Replay is set up by the agent itself, masks all text in the browser by default, and returns each session as a transcript the agent can search.

Updated

What the Clarity MCP server does

Microsoft publishes the server as the npm package @microsoft/clarity-mcp-server (GitHub). It runs locally, started by your MCP client with npx, and authenticates with a Clarity Data Export API token. A project admin creates that token under Settings, Data Export.

It has three tools:

  • query-analytics-dashboard: dashboard metrics from a plain-language query, such as sessions from one country in the last three days.
  • list-session-recordings: recordings filtered by URL, device, browser, OS, country, signals and more. A date range is required, and one call returns 1 to 250 sessions with metadata and links to the recordings.
  • query-documentation-resources: snippets from Clarity's documentation.

The Data Export API behind the token has firm limits (Microsoft Learn):

  • 10 requests per project per day.
  • Data from the last 1 to 3 days only.
  • Up to three dimensions per request.
  • At most 1,000 rows per response, with no pagination.

Microsoft's post announcing the MCP server gives the same 10 requests per project per day. Clarity itself is free, with no traffic limits and no sampling, and keeps recordings for 30 days (Clarity FAQ).

Hotjar and MCP

Hotjar is now part of Contentsquare, and new Hotjar accounts can no longer be created; new users are pointed to Contentsquare's free plan (Contentsquare). Contentsquare has its own MCP connector for Claude. Its announcement says it works on any Contentsquare plan, including Free, and answers questions about frustration and rage-click metrics, funnels and experiments.

Prompt for your agent

To have the agent set up replay and read the sessions itself, paste this into Claude Code, Cursor or Codex.

Paste this into Claude Code, Cursor or Codex

Turn on session replay for this project with AgentFirstStack Replay. Ask me before you start: recording sessions is a privacy decision. 1. Read the manual: https://replay.agentfirststack.com/llms.txt 2. If this project's .env already has AGENTFIRSTSTACK_API_KEY, use it. Otherwise get a key with: curl -X POST https://agentfirststack.com/v1/signup Save api_key in .env as AGENTFIRSTSTACK_API_KEY. 3. Create a replay site for the production domain. If the site runs AgentFirstStack analytics, pass its analytics_site_id; otherwise add the returned script tag to <head>. 4. Keep the default strict masking. Unmask only non-personal UI text: nav, buttons, links, headings and labels. 5. Deploy, open the homepage with ?afsr=1, click around, then run verify until it passes. 6. Use search_sessions, get_session_transcript and summarize_sessions to tell me where visitors get stuck. 7. Write the replay site id in AGENTFIRSTSTACK.md (never the key), and create a claim link for me with POST https://agentfirststack.com/v1/claim-link.

How AgentFirstStack Replay works

R=https://replay.agentfirststack.com
H="Authorization: Bearer $AGENTFIRSTSTACK_API_KEY"

# A replay site; linked to analytics, the analytics snippet loads the recorder
curl -s -X POST $R/v1/sites -H "$H" -H 'content-type: application/json' \
  -d '{"domain":"example.com","analytics_site_id":"site_..."}'

# Show non-personal UI text in transcripts; everything else stays masked
curl -s -X PATCH $R/v1/sites/$RSITE -H "$H" -H 'content-type: application/json' \
  -d '{"unmask_selectors":["nav","button","a","h1","h2","label"]}'

# After one visit to https://example.com/?afsr=1: check the install and verify the domain
curl -s -X POST $R/v1/sites/$RSITE/verify -H "$H"

# The most frustrated sessions with a rage click, then one of them as text
curl -s "$R/v1/sites/$RSITE/sessions?sort=frustration&signal=rage_click" -H "$H"
curl -s "$R/v1/sites/$RSITE/sessions/$SESSION/transcript" -H "$H"

A transcript reads like a log. Each line is one step, with a stable CSS selector the agent can try on the live page. Masked text shows as asterisks unless you unmasked it:

[00:00.0] page "/pricing" · load · from "google.com" · stayed 15s · saw 64% of the page
[00:05.1] click button "Start trial" {"#plans > div:nth-of-type(2) > button.cta"}
[00:09.3] click x4 in 0.8s button "Pay" {"#checkout button.pay"}  [RAGE DEAD ERROR-CLICK]
[00:09.5] JS error "TypeError: Cannot read properties of undefined (reading 'id')" after click on {"#checkout button.pay"}  [ERROR-CLICK]

summarize_sessions groups patterns across many sessions (top rage-click targets, dead clicks, JS errors, exit pages) with example session ids. get_heatmap, list_errors and get_funnel_dropoffs return the rest as JSON. The replay manual has every route and tool.

Clarity MCP and AgentFirstStack Replay compared

Microsoft Clarity MCP serverAgentFirstStack Replay
Who sets it upA person creates a Clarity project and adds its tracking code; a project admin creates the API tokenThe agent: one POST for a key, one call to create the site, then verify
How it runsA local process your MCP client starts with npxA remote MCP server (Streamable HTTP) and a REST API
Sessionslist-session-recordings: 1 to 250 per call, with links to the recordingssearch_sessions by page, signal, error, device, country or frustration; transcripts as text or JSON
AggregatesDashboard metrics from a plain-language query. The Data Export API: 10 requests a day, last 1 to 3 daysSummaries, click and scroll heatmaps, grouped JS errors and funnel drop-offs
SignalsDead, rage and error clicks, quick backs, excessive scrolling, script errorsRage, dead and error clicks, quick backs, excessive scrolling, JS errors, and a 0 to 100 frustration score
Default maskingBalanced: numbers and email addresses masked (masking)Strict: all text and inputs masked in the browser
VolumeNo traffic limits and no samplingHosted: 200 sessions per site a day, up to 30 minutes and 2 MB each
Retention30 days; favorites and a random sample up to 9 months (FAQ)Up to 14 days on the hosted service
Deleting one visitor's dataDelete the whole project, per Clarity's FAQdelete_visitor_data by user id, visitor id or session ids
Price and sourceFree; the tracking code is open sourceFree hosted; the whole service is MIT licensed

When to choose which

Clarity fits when:

  • A person already uses Clarity and wants an AI client to answer questions about it.
  • You need every session at full traffic, with no sampling and no daily session cap.
  • You want a human dashboard with recordings, heatmaps and longer retention.

AgentFirstStack Replay fits when:

  • The agent has to set replay up itself, without a person creating an account or a token.
  • The agent needs to read many sessions as text, without a 10-request daily quota.
  • You want strict masking by default and deletion per visitor. See session replay for AI agents for the full setup.

Microsoft Clarity, Hotjar and Contentsquare belong to their owners. AgentFirstStack isn't affiliated with Microsoft, Hotjar or Contentsquare. Details come from their public docs and pages, checked on 4 November 2026.

Questions

Can the Clarity MCP server read session recordings?

It can list them. Microsoft's README describes list-session-recordings, which returns up to 250 sessions per call with metadata and links to each recording, filtered by date and other fields. You watch the recordings in Clarity.

What are the Clarity Data Export API limits?

Per Microsoft's documentation: 10 requests per project per day, data from the last 1 to 3 days, up to three dimensions per request, and 1,000 rows per response with no pagination.

Is there a Hotjar MCP server?

Hotjar is now part of Contentsquare, which offers an MCP connector for Claude on all its plans, including Free. Third-party Hotjar MCP servers also exist; check what they can read and where your credentials go before you connect one.