Connect
Microsoft Clarity: connect projects and read site behaviour
TL;DR
Microsoft Clarity connects with one Data Export token per project. The agent has five reads and no writes: the projects, the requests left today, the dashboard numbers by up to three breakdowns, ranked landing-page opportunities and traffic sources. Clarity's API reaches back 1–3 days only and allows 10 requests per project per day; the agent reuses answers and says when data is missing or may be incomplete.
Connect
- 1In the Clarity project, a project admin opens Settings → Data Export → Generate new API token.
- 2On Integrations, press Connect a project on the Microsoft Clarity card, name the project, paste the token and press Check and save. Checking spends one of the project's 10 requests for the day, and that answer becomes the project's first saved report.
- 3Repeat for every project — each has its own token. Replace token swaps a token in place and refuses a token from another project; Check token spends one request to confirm it still works; Remove deletes the stored token here (it keeps working in Clarity until a project admin deletes it there).
Tools
| Tool | Kind | What it does |
|---|---|---|
| list_projects | Read | The connected projects and requests left today — spends no Clarity request |
| quota_status | Read | Requests left today for one project and the saved answers available — spends no request |
| report | Read | Sessions, bot sessions, users, pages per session, scroll depth, engagement time and friction signals, by up to 3 breakdowns; with none, the top browsers, devices, OS, countries, page titles, referrers and pages |
| page_insights | Read | Landing pages ranked by friction (20+ sessions by default), each with its numbers and what to look at |
| traffic_sources | Read | Behaviour by source, medium, campaign or channel, optionally by device or page |
Over MCP and the REST API the names are clarity__<tool> (for example clarity__page_insights). There are no writes.
Clarity's limits
- Window: the last 1, 2 or 3 days (24, 48 or 72 hours back from the call), never a calendar range.
- Requests: 10 per project per day, shared by every workspace that connected the project. A repeat of the same question within two hours is answered from the saved copy; when the day's requests are used up, the newest saved answer is used and labelled with the time it was read.
- Breakdowns: up to 3 per request — URL, source, medium, campaign, channel, device, country / region, browser, OS.
- Rows: up to 1,000, no paging. A list at 1,000 rows may be incomplete; the answer says so.
Reading the numbers honestly
- No human sessions in the window means no data — bots are counted apart — and the agent says so instead of reporting zero problems.
- A breakdown counts a session under every value it touched, so the rows do not add up to the project total.
- The landing-page thresholds (rage clicks from 5 % of sessions, dead clicks and quick backs from 10 %, scroll depth under 40 %, at least 20 sessions) are ours, not Clarity's, and every answer states them.
Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
| The daily limit is used up | The project used its 10 requests today | Use the saved answer, or ask again tomorrow (our count resets at midnight UTC) |
| A token refused as invalid or expired | The token was deleted or regenerated in Clarity | Generate a new token and use Replace token |
| A replacement refused as another project's token | The token was made in a different Clarity project | Connect that project as its own row |
| No data for the window | No human sessions in the last 1–3 days | Check the Clarity tag is installed; try 3 days |
Platform overview: Microsoft Clarity.
Frequently asked questions
- Can the agent change my Clarity settings or my site?
- No. The Clarity integration is read-only.
- Why only three days?
- Clarity's Data Export API returns only the last 1, 2 or 3 days. Use the Clarity dashboard for longer ranges.