Microsoft Clarity

Connect Microsoft Clarity so agents can answer traffic and engagement questions and pull matching session recordings

Connect a Microsoft Clarity project and CloudThinker agents can answer questions about traffic, engagement, and frustration signals, and list the session recordings behind them. The connection signs in with one Clarity API token (a secret key that belongs to a single Clarity project) and only reads data.

Prerequisites

• A Clarity project that is already collecting data from your site.
• The Admin role on that Clarity project, so you can generate API tokens.
• The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.

Setup

1. Generate an API token in Clarity

   Sign in to Clarity, open the project, and go to Settings → Data Export. Click Generate new API token and name it cloudthinker. Names are 4 to 32 characters with no spaces.

   Copy the token right away and keep it somewhere safe until the next step.

2. Open Microsoft Clarity in CloudThinker

   In the sidebar, click More → Workspace settings → Connections. On the Builtin Connections tab, search for Microsoft Clarity and click Connect.

3. Paste the token and connect

   Paste the token into CLARITY_API_TOKEN (the dialog shows the field under this exact name) and click Connect.

   Success state: the Connect Microsoft Clarity dialog closes and the connection shows Connected.

Clarity checks the token when an agent first uses it. A mistyped or revoked token can still show Connected, so run the verify prompt below before you rely on it.

Connection details

Field	Description	Example
CLARITY_API_TOKEN	API token generated under Settings → Data Export in your Clarity project	<your-api-token>

One token covers one project. To reach a second Clarity project, generate a token there and connect it separately.

To replace a saved token, open More → Workspace settings → Connections, select Microsoft Clarity, and click the pencil (Edit) icon on its row. In Edit Instance, click Replace… under Credentials, paste the new token, and click Save and test.

Required permissions

The token can read the analytics and recordings of the project that issued it, and nothing else. Clarity has no per-token scopes, so you control access by choosing which project issues the token and who can generate one.

Generate a token used only by CloudThinker. You can then revoke it in Clarity without breaking any other tool that reads the same project.

Agent capabilities

CloudThinker uses Microsoft’s Clarity MCP server (Model Context Protocol, a standard way for agents to call a tool). Every tool is read-only.

Capability	What agents can do
Dashboard analytics	Ask for sessions, users, popular pages, referrers, channels, and campaigns, broken down by device, browser, OS, or country
Behavior and performance	Report scroll depth, dead clicks, rage clicks, quick backs, JavaScript errors, and Core Web Vitals
Session recordings	List recordings filtered by date, page URL, device, browser, OS, country, UTM source, or frustration signals, sorted by start time, duration, clicks, or page count. Up to 250 per request

Agents can also look up Clarity’s own documentation, for example how custom events work.

Dashboard questions cover only the last 1 to 3 days (24, 48, or 72 hours), because that’s all Clarity’s API returns. Ask for “last 3 days” or less, and use the Clarity dashboard for longer ranges. Clarity answers a single metric per query best, so CloudThinker splits a broad question into several queries. Each one is a separate call to Clarity’s API, which allows 10 dashboard calls per project per day, so narrow questions go further.

Verify the connection

How many Clarity sessions did we get in the last 3 days, broken down by device type?

A working connection returns real session counts for PC, Mobile, and Tablet. A generic explanation of Clarity, or an authorization error, means the token is wrong.

Example prompts

Which 5 pages had the most rage clicks in Clarity over the last 3 days?
List the 10 longest Clarity sessions from mobile devices yesterday that hit a JavaScript error
Compare average scroll depth on mobile and desktop for /pricing over the last 2 days

Troubleshooting

Connected, but every request fails with an authorization error

Clarity rejected the token. It may be revoked, mistyped, or issued by a different project. Generate a new token in the right project, open the connection, and replace the saved token.

This connection did not respond in time. Try connecting again.

CloudThinker could not start the Clarity server before the timeout. Click Connect again. If it still times out, check that Clarity itself loads for your project, then email [e-mail] with the time of the failure.

Answers stop partway, or Clarity reports a rate limit

Clarity allows 10 dashboard calls per project per day, and a broad question uses several calls. Wait until the next day, then ask for one metric and one breakdown at a time.

Results cover the wrong days

Dashboard questions can only reach back 1 to 3 days, so a question about the last week or month returns at most the last 3 days. Use the Clarity dashboard for longer ranges. Clarity also reports in UTC, so “yesterday” follows UTC rather than your local time. Give an explicit date range, or name your time zone in the prompt.

The answer is vague or mixes several metrics

Clarity answers one metric per query best. Ask for a single metric, one breakdown, and an explicit time range, then follow up with the next question.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Replace the token when people leave. When someone with access to the Clarity project leaves, generate a new token and replace the saved one.
• Keep the token out of chat. Paste it only into the connection dialog, never into a chat message or a repository.

Related

PostHog Connection

Add product analytics, feature flags, and error tracking next to Clarity

Connections Overview

See how access, writes, and credential rotation work for every connection