01 · Overview
What the Ryze AI Microsoft Clarity MCP server is
The short version
- 01Microsoft Clarity connects to a Ryze AI workspace with a Data Export API token from one Clarity project. Your AI client then connects to Ryze AI with one URL (see Setup).
- 02One tool,
clarity__read, returns Clarity behavior insights for the last 1 to 3 days, broken down by up to 3 dimensions. - 03It covers sessions, scroll depth, engagement time, popular pages, referrers and the friction signals: dead clicks, rage clicks, excessive scrolling, quickbacks, script errors and error clicks.
- 04Clarity allows 10 export requests per project per day and 1,000 rows per answer. There are no session recordings and no heatmaps.
- 05Works with any Ryze AI plan or trial. Paid Ads is $89/mo with a 7-day free trial.
- Server name
- Ryze AI (Microsoft Clarity tool)
- Endpoint
- https://connector.get-ryze.ai/mcp
- Transport
- Remote MCP over HTTP
- Client sign-in
- OAuth to Ryze AI, up to 20 workspaces per connection
- Clarity sign-in
- Data Export API token for one Clarity project
- Clarity API
- Data Export API, project-live-insights endpoint
- Clarity tools
- 1 (read)
- Also on this URL
- Google Ads, Meta Ads, Google Analytics 4, Search Console, HubSpot, Shopify
- Price
- Any Ryze AI plan or trial · Paid Ads $89/mo
- Checked
- November 8, 2026
“Microsoft Clarity MCP” can mean three things. Microsoft publishes an open-source package, @microsoft/clarity-mcp-server, that you run on your own computer. Clarity also has a plain Data Export API that scripts call directly. A hosted server such as the Ryze AI one sits on that same API and adds sign-in through a single URL. This page documents the Ryze AI server and compares it with Microsoft’s package in section 06.
01
One token, no OAuth screen
Clarity authorizes the export with a token that a project admin generates under Settings, Data Export. You paste it into Ryze AI once. Nothing is installed on your site and nothing runs on your computer.
02
Behavior and friction metrics
The tool returns sessions, scroll depth, engagement time, popular pages and referrers, plus friction signals: dead clicks, rage clicks, excessive scrolling, quickbacks, script errors and error clicks.
03
Up to 3 breakdowns
Split any answer by browser, device, country or region, OS, source, medium, campaign, channel or URL. A request can carry 3 of them at once, such as device, campaign and URL.
04
A 1 to 3 day window
Clarity serves only the last 24, 48 or 72 hours through this API. Questions about this week or this month cannot be answered from it, and the page says so up front in the limits table.
05
A small daily budget
Clarity allows 10 export requests per project per day and 1,000 rows per answer. The agent has to pick its breakdowns with care, and you can help by naming the one question you care about.
06
Read only
The only Clarity tool is a read tool. The connector cannot change settings, filters or tracking in your Clarity project.
07
Connect from the chat
Ask the Ryze AI agent in Claude or ChatGPT to connect Microsoft Clarity and it sends a one-time link, valid once and for 24 hours, to a page where you paste the token.
08
Next to ad data
Google Ads, Meta Ads and Google Analytics 4 tools answer on the same connection, so a chat can compare ad campaign names with the Clarity campaign dimension.
02 · Tool reference
One Clarity tool and what it returns
The tool needs workspace when your client connection covers more than one Ryze AI workspace. Which metrics come back depends on how the question is phrased and which breakdowns the agent picks. The tool name comes from the Ryze AI connector definition. No Clarity project was connected in a live session on Nov 8, 2026, so the input names above are described in plain words and not copied from a live tool list.
| Tool | Access | What it does | Inputs |
|---|---|---|---|
clarity__read | read | Fetches Clarity behavior insights for the connected project over the last 1 to 3 days: traffic, scroll depth, engagement time, popular pages, referrers, dead clicks, rage clicks, excessive scrolling, quickbacks, script errors and error clicks. | workspace · days (1 to 3) · up to 3 breakdown dimensions |
Metrics in the Clarity export
| Clarity metric | What it measures | Note |
|---|---|---|
| Traffic | Sessions, bot sessions, distinct users and pages per session | Sample response includes a bot session count next to total sessions |
| Scroll Depth | How far visitors scroll down a page | Break down by device to compare phone and desktop |
| Engagement Time | Time spent actively on a page | Pair with Popular Pages |
| Popular Pages | The pages that receive the most visits | Includes the page title |
| Referrer URL | Where visitors came from | Complements the Source and Medium dimensions |
| Dead Click Count | Clicks that produce no response on the page | A friction signal |
| Rage Click Count | Repeated fast clicks in one spot | A friction signal |
| Excessive Scroll | Scrolling far more than usual on a page | A friction signal |
| Quickback Click | A visitor jumps to a page and returns almost at once | A friction signal |
| Script Error Count | JavaScript errors raised during sessions | A technical signal |
| Error Click Count | Clicks that coincide with a script error | A technical signal |
Metric names are Clarity’s own, from the Clarity Data Export API reference, checked Nov 8, 2026.
Breakdown dimensions
Up to 3 per request. Ad and analytics tools on the same URL are documented on Google Ads MCP, Meta Ads MCP and Google Analytics MCP.
03 · Use cases
Check this week’s landing pages for friction
Because the export covers only the last 1 to 3 days, the best questions are about what is happening on the site right now: a campaign that just launched, a page you just changed, a release that may have broken something. Rage clicks, dead clicks and script errors by URL point at the page to open in Clarity next. The agent does not watch recordings, so it can name the page and the pattern but not what the visitor saw.
- “Show rage clicks and dead clicks by URL for the last 3 days, then list the 5 pages with the most.”
- “Break popular pages down by campaign and medium, and tell me which paid campaigns land on pages with high excessive scrolling.”
- “Which source and medium pairs have the lowest engagement time in the last 72 hours?”
- “Compare scroll depth by device for the last 3 days and name the pages where phones scroll much less than desktop.”
- “Which browser has the most script errors yesterday, and on which URLs?”
- “Split quickbacks by device and URL and show the top 10 rows.”
- “Give me sessions and distinct users by source for the last 24 hours.”
- “Which countries sent traffic to my pricing page in the last 2 days, and how long did they stay?”
- “List the referrers behind my most popular pages today.”
- “Pull Google Ads campaign cost for the last 3 days, then show Clarity rage clicks for the same campaign names.”
- “Compare Meta Ads campaign names with the Clarity campaign dimension and flag campaigns that bring traffic but no engagement.”
- “Which landing page URLs have both high ad traffic and high dead clicks?”
Every answer comes from your own Clarity project and ad accounts, so no sample numbers are shown here. With only 10 requests per project per day, one prompt that names the breakdowns you want uses less of the budget than a run of open questions.
04 · Setup
Connect Clarity once, then add the URL to each client
Step 1: connect Microsoft Clarity in Ryze AI
- 01In Clarity, open the project, then Settings, Data Export, Generate new API token. Give the token a name and copy it. Each token belongs to one project, and only project admins can manage tokens.
- 02In the Ryze AI app, open Integrations, click Connect on the Microsoft Clarity card and paste the token. Add a Project name if you want a label, then click Continue.
- 03Or skip the app: ask the Ryze AI agent in Claude or ChatGPT to connect Microsoft Clarity. It sends a one-time link, valid once and for 24 hours, to a page where you paste the token.
Details are in the Ryze AI Microsoft Clarity guide. The one-time link is refused while a Clarity project is already connected in the workspace; switch projects in the app.
Step 2: Claude on the web or desktop
- 01Go to Customize, Connectors.
- 02Choose + Add, then Add custom connector. Enter Ryze AI as the name and
https://connector.get-ryze.ai/mcpas the MCP server URL, then continue. Leave authentication on the OAuth sign-in Claude detects; do not choose No sign in. - 03Click Connect, sign in to Ryze AI, choose the workspace that holds Clarity and click Allow connection.
- 04Start a new chat. Claude keeps the tool list from the moment the connector is added, so if you connect Microsoft Clarity afterwards, remove the connector, add it again and open a new chat.
Anthropic lists custom connectors on Free, Pro, Max, Ultra, Team and Enterprise, and Free allows one. On Team and Enterprise an Owner adds Ryze AI under Organization settings, Connectors, and each member then clicks Connect.
Step 2: ChatGPT
Open Plugins (chatgpt.com/plugins), choose the plus button, then Add custom MCP server. Name it Ryze AI, enter https://connector.get-ryze.ai/mcp, choose OAuth, accept the risk warning, create it as a plugin and complete the Ryze AI sign-in with the workspace that holds Clarity. Then install it, start a new conversation, type @ and pick Ryze AI.
OpenAI documents full custom MCP servers on Business and Enterprise/Edu, where only admins and owners create them, and read-only access for Pro users. It does not mention Free, Go or Plus. Web only: custom MCP servers cannot be connected on mobile. After connecting Microsoft Clarity later, remove the app and add it again so ChatGPT sees the new tool.
Step 2: Cursor and Claude Code
{ "mcpServers": {
"ryze": { "url": "https://connector.get-ryze.ai/mcp" }
} }Cursor runs OAuth with PKCE and dynamic client registration, so sign in on the Ryze AI page and click Allow connection. Cursor asks for approval before using MCP tools by default.
claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope userInside Claude Code run /mcp, select ryze and authenticate. The developer page has the other client entries and the API key option. Ryze AI for developers.
05 · Token access
Who can create the Clarity token, and what it reaches
| Who can create the token | Clarity says only project admins can manage access tokens. Generate it under Settings, Data Export, Generate new API token, and give it a name of 4 to 32 characters. |
| Which project | Each token belongs to one Clarity project, and a Ryze AI workspace holds one Clarity connection. The project name field in Ryze AI is optional and only labels the connection. |
| What the token reaches | Clarity describes the token as an API access token for exporting dashboard data. Ryze AI uses it for the read tool only, and the Clarity export has no write endpoint. |
| Token handling | Clarity advises storing tokens securely and replacing a token promptly when a person with access leaves the project. Replace it in Clarity, then reconnect Microsoft Clarity in Ryze AI with the new value. |
Clarity documents the token as a JWT sent as a Bearer header; Ryze AI sends it for you. Clarity does not publish separate scopes for the export token, so there is no scope list to review. Source: Microsoft Learn, Clarity Data Export API, checked Nov 8, 2026.
Removing access
In Ryze AI, open View on the Microsoft Clarity card and use the trash icon to disconnect. In Claude, open Customize, Connectors, Ryze AI and click Disconnect, which cuts off every workspace at once. To make the old token useless, replace it in Clarity under Settings, Data Export.
06 · Compare
Ryze AI vs Microsoft’s own Clarity MCP server
Three ways to reach Clarity data from an AI client
| Option | Built for | How you connect | Clarity data | Changes |
|---|---|---|---|---|
| Ryze AI hosted server | Marketers who also run ads | Clarity Data Export API token pasted into Ryze AI, then OAuth sign-in from the client | Last 1 to 3 days of insights, up to 3 dimensions | Read only |
| Microsoft clarity-mcp-server (npm package, MIT license) | Developers who run a local MCP server | Clarity Data Export API token passed as a command argument in the client config | Analytics dashboard query, session recording list, Clarity documentation search | Read only (list and query tools) |
| Clarity Data Export API called directly | Developers who write scripts | Authorization: Bearer token on a GET request | Same project-live-insights data, JSON | Read only |
Sources: the microsoft/clarity-mcp-server repository (138 stars, MIT license, last commit Feb 24, 2026) and the Clarity Data Export API reference, checked Nov 8, 2026.
Ryze AI and Microsoft’s package side by side
| Ryze AI | Microsoft clarity-mcp-server | |
|---|---|---|
| Where it runs | Hosted by Ryze AI, one URL | On your computer through npx or a global npm install (Node.js 16 or newer) |
| Tools for Clarity | 1: clarity__read | 3: query-analytics-dashboard, list-session-recordings, query-documentation-resources |
| Session recordings | Not available | Lists recordings with filters, according to its README |
| Where the token lives | Stored in the Ryze AI connection for the workspace | Written into the client config file as an argument |
| Other data in the same chat | Google Ads, Meta Ads, Google Analytics 4, Search Console, HubSpot, Shopify | Clarity only |
| Clients | Claude, ChatGPT, Cursor and other remote MCP clients | Clients that start local servers, such as Claude Desktop; its README documents a VS Code install |
| Price | Any Ryze AI plan or trial. Paid Ads $89/mo, 7-day free trial | MIT licensed, free to install |
As published on Nov 8, 2026. Microsoft may add tools to its package, so check its README before you decide.
Which to pick: if you want to look at session recordings from an AI client, Microsoft’s package lists them and Ryze AI does not. If you want nothing installed, one remote URL, and Clarity friction data in the same chat as Google Ads, Meta Ads or Google Analytics 4, Ryze AI fits. If you are writing a script that runs on a schedule, call the Data Export API directly.
07 · API limits
Clarity limits an agent runs into
| Date range | Only the previous 1 to 3 days (24, 48 or 72 hours). There is no older history and no custom date range. |
| Requests per day | 10 API requests per project per day. After that Clarity returns 429 TooManyRequests with the message Exceeded daily limit. |
| Dimensions | Up to 3 per request, from browser, device, country or region, OS, source, medium, campaign, channel and URL. |
| Rows | 1,000 rows per response, and the response cannot be paginated. |
| Time zone | Results are in UTC. |
| Response shape | JSON, one block per metric. Clarity notes that the full response can hold more metrics and dimensions than its sample shows. |
| Not available | Session recordings and heatmaps are not part of this export, so Ryze AI cannot read them. |
| Plan | Ryze AI tools need an active plan or free trial. Without one, the connector can only list workspaces and connect platforms. |
From Microsoft Learn, Clarity Data Export API (last updated Nov 26, 2024) and the Ryze AI Microsoft Clarity guide, checked Nov 8, 2026.
08 · Approvals and safety
What the connector can and cannot change
Read only
The only Clarity tool is a read tool, so the connector does not change anything in your Clarity project.
Approvals in Claude
Under Customize, Connectors, Ryze AI, Tool permissions, you can set approvals per tool. Claude lists write and delete tools for Needs approval; Clarity has neither.
Approvals in the Ryze AI app
The Tool approvals picker in the Ryze AI chat starts on Skip all approvals. Choose a stricter option if you want to see each tool call before it runs.
Spend the daily budget on purpose
Each tool call can use 1 of the 10 daily requests, so a loop of repeated questions can use up the day. Ask for one breakdown set at a time.
One project per workspace
A workspace holds one Clarity project. Another project can live in another workspace, and one Claude or ChatGPT connection covers up to 20 workspaces.
Policies
Read the MCP privacy policy, the MCP terms, the security policy and the permissions guide.
09 · Errors and fixes
Microsoft Clarity MCP errors and what they mean
| Message or symptom | Cause | Fix |
|---|---|---|
| The token is rejected when connecting | The token was copied from another project, is mistyped, or was replaced in Clarity. | Generate a fresh token under Settings, Data Export in the right project and paste it again. |
| Clarity returns 401 Unauthorized | Clarity lists a missing, invalid or expired token as the cause. | Replace the token in Clarity and reconnect Microsoft Clarity in Ryze AI. |
| Clarity returns 403 Forbidden | Clarity says the token is not authorized for the operation. | Ask a project admin to generate a new token. |
| The agent says there is no more data today | The 10 requests per project per day are used up. Clarity answers 429 with Exceeded daily limit. | Wait until the next day and ask one precise question instead of several broad ones. |
| Clarity returns 400 BadRequest | Clarity lists invalid request parameters, for example a fourth dimension or a day count above 3. | Ask again with up to 3 breakdowns and a window of 1 to 3 days. |
| The answer has no history beyond 3 days | The Data Export API serves only the last 1 to 3 days. | Ask about the last 24, 48 or 72 hours. For longer trends use Clarity's own dashboard. |
| The agent cannot show a recording or heatmap | The export has neither. | Open the recording or heatmap in Clarity and ask the agent about the page's numbers. |
| Clarity tools are missing in Claude or ChatGPT | Microsoft Clarity was connected after the connector was added and the client kept its old tool list. | Remove the Ryze AI connector, add it again and open a new chat. |
| The connection link is refused | Clarity holds one connection per workspace, and the one-time link is refused while one exists. | Switch projects in the Ryze AI app: View on the card, trash icon, then connect again. |
| Tools reply that a subscription is required | The workspace has no active Ryze AI plan or trial. | Start a plan or trial under Organization Settings, Billing, then retry. |
The 400, 401, 403 and 429 rows come from the response codes in Clarity’s Data Export API reference. The rest are Ryze AI connection cases from the Ryze AI Microsoft Clarity guide. Questions that are not covered go to Ryze AI support.
10 · FAQ
Microsoft Clarity MCP questions
What is a Microsoft Clarity MCP server?
An MCP server lets AI clients such as Claude, ChatGPT and Cursor call Microsoft Clarity through tools. Microsoft publishes an open-source package, @microsoft/clarity-mcp-server, that runs on your own computer. Ryze AI runs a hosted one with a single read tool, clarity__read, on the same URL as its Google Ads, Meta Ads and Google Analytics 4 tools.
Does Microsoft have an official Clarity MCP server?
Yes. Microsoft's clarity-mcp-server repository on GitHub, MIT licensed, has 3 tools: query-analytics-dashboard, list-session-recordings and query-documentation-resources. It runs locally through npx or a global npm install and takes a Clarity Data Export API token as an argument. At the time of checking, its last commit was on Feb 24, 2026.
What does the Ryze AI Microsoft Clarity tool return?
The clarity__read tool returns Clarity behavior insights for the connected project over the last 1 to 3 days: traffic, scroll depth, engagement time, popular pages, referrers, dead clicks, rage clicks, excessive scrolling, quickbacks, script errors and error clicks. Results can be broken down by up to 3 of browser, device, country or region, OS, source, medium, campaign, channel and URL.
What is the Microsoft Clarity API?
Clarity's Data Export API is a REST endpoint, project-live-insights, that returns dashboard data as JSON for the previous 1 to 3 days. A project admin generates a token under Settings, Data Export, and the request sends it as a Bearer header. Clarity allows 10 requests per project per day, up to 3 dimensions per request and 1,000 rows per response.
How do I set up a Clarity MCP server in Claude?
Generate a token in Clarity under Settings, Data Export, connect Microsoft Clarity on the Integrations page in Ryze AI, then in Claude open Customize, Connectors, Add custom connector, paste https://connector.get-ryze.ai/mcp, click Connect, allow the workspace and open a new chat. If Clarity was connected after the connector, remove and re-add the connector first. Every client is covered in the setup section.
Does it work in ChatGPT?
Yes, through a custom MCP server in ChatGPT Plugins with OAuth. OpenAI documents full custom MCP servers on Business and Enterprise/Edu and read-only access on Pro, and it does not mention Free, Go or Plus. Custom MCP servers work on the web only. The Clarity tool is a read tool, so the Pro read-only limit does not block it.
Can the AI see session recordings or heatmaps?
No. The Clarity Data Export API has neither, so Ryze AI cannot read them. Microsoft's own clarity-mcp-server lists session recordings with filters, so use that package if recordings matter. With Ryze AI, the agent can name the pages with rage clicks or dead clicks, and you open the recording or heatmap in Clarity.
Why does it only show the last 1 to 3 days?
Clarity's Data Export API serves only the previous 24, 48 or 72 hours, so Ryze AI cannot return older history or a monthly trend. Ask about what is happening now, such as a campaign that launched yesterday or a page changed this week. For longer trends use Clarity's own dashboard.
How many questions can I ask per day?
Clarity allows 10 export requests per project per day. After that it answers 429 with Exceeded daily limit until the next day. Each answer is also capped at 1,000 rows and cannot be paginated, so a prompt that names the breakdowns you want spends less of the budget than several open questions.
Is the Microsoft Clarity MCP server free?
Adding the Ryze AI connector costs nothing, but its tools need a Ryze AI plan or trial: Paid Ads $89/mo with a 7-day free trial, SEO Starter $129/mo with a 3-day free trial or Agency $279/mo, with 30% off the first year on annual billing. Microsoft’s own clarity-mcp-server is MIT licensed and free to install. See the pricing page.
Can I connect more than one Clarity project?
Not in one workspace. Each Clarity token belongs to one project and a Ryze AI workspace holds one Microsoft Clarity connection. To switch, click View on the card, disconnect with the trash icon and connect again. Another project can live in another workspace, and one Claude or ChatGPT connection can cover up to 20 workspaces.
Can Claude read Clarity next to my ad data?
Yes. Google Ads, Meta Ads and Google Analytics 4 tools answer on the same connection, so Claude can compare campaign names with the Clarity campaign dimension. Ryze AI is the best Clarity MCP option for putting recent friction data next to ad data in one chat, but it reads only the last 1 to 3 days and has no session recordings.
Can the connector change anything in Clarity?
No. clarity__read is the only Clarity tool and it is a read tool, so it cannot change settings, filters or tracking in your project. In Claude, approvals are set per tool under Customize, Connectors, Ryze AI, Tool permissions.
11 · Compatibility
Where the Clarity tool runs
12 · Related
Other integrations and guides
Changelog
Page checked Nov 8, 2026. First version. Setup steps, limits and error codes were checked on this date against the Ryze AI help center, Microsoft Learn (Clarity Data Export API) and the microsoft/clarity-mcp-server repository. The tool name comes from the Ryze AI connector definition and was not seen in a live tool list.