Connect AI agents to Microsoft Clarity

Scalekit connector

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.

Tools: 3
What they doRead · write · destructive: 3 · 0 · 03 read0 write0 destructive
Users sign in with: Access token

Setup

Install the SDK
- Node.js
- Python
Terminal window
npm install @scalekit-sdk/node dotenv
Terminal window
pip install scalekit-sdk-python python-dotenv
Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
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.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'microsoftclarity'
13
const identifier = 'user_123'
14

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

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'microsoftclarity_get_project_live_insights',
27
  toolInput: { numOfDays: 1 },
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "microsoftclarity"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Microsoft Clarity:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={"numOfDays":1},
27
    tool_name="microsoftclarity_get_project_live_insights",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user opens the link once and enters their Microsoft Clarity credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

microsoftclarity_get_project_live_insightsExport 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.Read-only
Get Project Live Insights
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.
Inputs
numOfDaysintegerrequired
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 123
dimension1string
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 BrowserDeviceCountry/RegionOSSourceMediumCampaignChannelURL
dimension2string
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 BrowserDeviceCountry/RegionOSSourceMediumCampaignChannelURL
dimension3string
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 BrowserDeviceCountry/RegionOSSourceMediumCampaignChannelURL
microsoftclarity_list_session_recordingsList 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.Read-only
List Session Recordings
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.
Inputs
endstringrequired
End of the time window as a UTC ISO 8601 timestamp with milliseconds. Must be after start. Example: 2026-10-09T00:00:00.000Z.
startstringrequired
Start of the time window as a UTC ISO 8601 timestamp with milliseconds. Example: 2026-10-08T00:00:00.000Z.
countinteger
Number of sample recordings to return, from 1 to 250. Defaults to 100. Example: 50.default 100
filtersobject
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_bystring
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_DESCSessionStart_ASCSessionDuration_ASCSessionDuration_DESCSessionClickCount_ASCSessionClickCount_DESCPageCount_ASCPageCount_DESCdefault SessionStart_DESC
microsoftclarity_query_analytics_dashboardAnswer a natural-language analytics question about the Clarity project the API token belongs to, over a time range you name in the query.Read-only
Query Analytics Dashboard
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.
Inputs
querystringrequired
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.
timezonestring
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

Setup

Install the SDK

Set your credentials

Create the Microsoft Clarity connection

Authorize a user and make your first call

Tools

Call it

Returns

Get Project Live Insights

Inputs

List Session Recordings

Inputs

Query Analytics Dashboard

Inputs

Related: other Analytics connectors