> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Microsoft Clarity

The Microsoft Clarity connector lets your AI agent act in each user's Microsoft Clarity account. Each user connects their own Microsoft Clarity access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 3 tools.

**Authentication:** Bearer Token
**Categories:** Analytics
**Tools:** 3: 3 read, 0 write, 0 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=MICROSOFTCLARITY)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Microsoft Clarity connection

   In **AgentKit > Connections**, create a Microsoft Clarity connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'microsoftclarity'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Microsoft Clarity:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'microsoftclarity_get_project_live_insights',
     toolInput: { numOfDays: 1 },
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "microsoftclarity"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Microsoft Clarity:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={"numOfDays":1},
       tool_name="microsoftclarity_get_project_live_insights",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Microsoft Clarity credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'microsoftclarity_get_project_live_insights',
  toolInput: {
    numOfDays: 1,
  },
  connector: 'microsoftclarity',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="microsoftclarity_get_project_live_insights",
    tool_input={
        "numOfDays": 1,
    },
    connection_name="microsoftclarity",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `microsoftclarity_get_project_live_insights`

Get Project Live Insights · Read-only

Export recent analytics for the Microsoft Clarity project the API token belongs to, covering the last 24, 48, or 72 hours, optionally broken down by up to three dimensions such as browser, device, country, or URL.
Returns a JSON array of metric groups, each with a metric name and a list of rows. Metrics include traffic, engagement time, scroll depth, popular pages, dead clicks, rage clicks, quickback clicks, excessive scroll, script errors, and error clicks. Results are in UTC, capped at 1,000 rows, and not paginated.
Use this for aggregate behavior and traffic insights. Each project is limited to 10 requests per day and further calls return a 429 error, so request the dimensions you need in a single call.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `numOfDays` (`integer`, required): Number of days of data to export, counted back from now. Must be 1 (last 24 hours), 2 (last 48 hours), or 3 (last 72 hours). Example: 1. One of: `1`, `2`, `3`.
- `dimension1` (`string`, optional): First dimension to break the insights down by. Must be one of Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, or URL. Leave empty for no breakdown. Example: Country/Region. One of: `Browser`, `Device`, `Country/Region`, `OS`, `Source`, `Medium`, `Campaign`, `Channel`, `URL`.
- `dimension2` (`string`, optional): Second dimension to break the insights down by, combined with dimension1. Must be one of Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, or URL. Set dimension1 first when using it. Leave empty for no second breakdown. Example: Device. One of: `Browser`, `Device`, `Country/Region`, `OS`, `Source`, `Medium`, `Campaign`, `Channel`, `URL`.
- `dimension3` (`string`, optional): Third dimension to break the insights down by, combined with dimension1 and dimension2. Must be one of Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, or URL. Set dimension1 and dimension2 first when using it. Leave empty for no third breakdown. Example: Browser. One of: `Browser`, `Device`, `Country/Region`, `OS`, `Source`, `Medium`, `Campaign`, `Channel`, `URL`.

Example input: `{"numOfDays":1}`

### `microsoftclarity_list_session_recordings`

List Session Recordings · Read-only

List a sample of session recordings from the Clarity project the API token belongs to for a UTC time window, with optional filters and sort order.
Returns the matching sample session recordings as JSON, up to 250 per call.
Use this to inspect individual sessions, for example sessions with rage clicks or JavaScript errors. Use query_analytics_dashboard for aggregate numbers and get_project_live_insights for the fixed last 24 to 72 hour metric export. The date filter is filled in automatically from start and end. This is the recordings endpoint behind Microsoft's Clarity MCP server.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End of the time window as a UTC ISO 8601 timestamp with milliseconds. Must be after start. Example: 2026-10-09T00:00:00.000Z.
- `start` (`string`, required): Start of the time window as a UTC ISO 8601 timestamp with milliseconds. Example: 2026-10-08T00:00:00.000Z.
- `count` (`integer`, optional): Number of sample recordings to return, from 1 to 250. Defaults to 100. Example: 50. Default: `100`.
- `filters` (`object`, optional): Optional object of extra filters that narrow which recordings are sampled. Leave it out to sample every session in the time window. Do not include a date entry, because it is filled in from start and end. Audience filters: userType (NewUser or ReturningUser); deviceType (a list drawn from Mobile, Tablet, PC, Email, Other); browser (a list of names such as Chrome, Edge, Firefox, Safari, Samsung, Opera); os (a list drawn from Android, iOS, Windows, MacOS, Linux, ChromeOS, WindowsMobile, BlackBerry, Other); country, city, and state (lists of place names). Traffic source filters: source, medium, and campaign (lists of UTM values); channel (a list drawn from OrganicSearch, Direct, Email, Display, Social, PaidSearch, Referral, Affiliate, Video, Audio, SMS, AITools, PaidAITools, Other). Page filters: visitedUrls, entryUrls, and exitUrls each take a list of objects with a url and an operator (contains, startsWith, endsWith, excludes, isExactly, isExactlyNot, matchesRegex, or excludesRegex). Frustration and error filters: rageClickPresent, deadClickPresent, excessiveScrollPresent, and quickbackClickPresent take true to keep only sessions with that behavior; javascriptErrors and clickErrors take a list of error text patterns, where an empty string matches any error. Range filters: sessionDuration (minutes), pagesCount, and sessionClickEventCount take an object with a min and a max, either of which may be null; scrollDepth takes a min and a max between 0 and 100. Example: {"deviceType": ["Mobile"], "country": ["United States"], "rageClickPresent": true, "visitedUrls": [{"url": "/checkout", "operator": "contains"}]}.
- `sort_by` (`string`, optional): Order of the returned recordings. Defaults to SessionStart_DESC (newest first). Use SessionDuration_DESC for the longest sessions, SessionClickCount_DESC for the most clicks, or PageCount_DESC for the most pages. Example: SessionStart_DESC. One of: `SessionStart_DESC`, `SessionStart_ASC`, `SessionDuration_ASC`, `SessionDuration_DESC`, `SessionClickCount_ASC`, `SessionClickCount_DESC`, `PageCount_ASC`, `PageCount_DESC`. Default: `SessionStart_DESC`.

Example input: `{"end":"<end>","start":"<start>"}`

### `microsoftclarity_query_analytics_dashboard`

Query Analytics Dashboard · Read-only

Answer a natural-language analytics question about the Clarity project the API token belongs to, over a time range you name in the query.
Returns the dashboard query result as JSON, such as top browsers, active time by device and country, or other traffic and engagement aggregates.
Use this for flexible aggregate questions with an explicit time range. Use get_project_live_insights for the fixed last 24 to 72 hour metric export with up to three dimension breakdowns, and list_session_recordings for individual sessions. Keep each query to one retrieval or aggregation task and state the time range in the query. This is the dashboard endpoint behind Microsoft's Clarity MCP server.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Natural-language analytics query focused on a single retrieval or aggregation task, with an explicit time range. Examples: Top browsers last 3 days; Active time for mobile devices in United States last week. If the user gave no time range, ask for one before calling.
- `timezone` (`string`, optional): IANA time zone name used to interpret the time range in the query, such as America/New_York or Europe/London. Defaults to UTC when omitted. Example: America/New_York. Default: `UTC`.

Example input: `{"query":"<query>"}`

## Related

Other Analytics connectors ([all 109](/agentkit/connectors/?category=analytics)):

- [Microsoft 365](/agentkit/connectors/microsoft365/): Scalekit connector, OAuth, 317 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Snowflake](/agentkit/connectors/snowflake/): Scalekit connector, OAuth, 42 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |