> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.cloudthinker.io/guide/security/roles.md).

## 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**.

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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

```text theme={null}
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

```text theme={null}
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

> [accordion] 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.

> [accordion] 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 [support@cloudthinker.io](mailto:support@cloudthinker.io) with the time of the failure.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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

> [card] [PostHog Connection](https://docs.cloudthinker.io/guide/connections/posthog.md)
>
> Add product analytics, feature flags, and error tracking next to Clarity

> [card] [Connections Overview](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> See how access, writes, and credential rotation work for every connection


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.