How do I use clarity-mcp-multi?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clarity-mcp-multi list my clients" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

clarity-mcp-multi

by Oak1997

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

clarity-mcp-multi

An MCP proxy that adds per-client token routing on top of Microsoft's official Clarity MCP server.

Why

The official server authenticates with a single Clarity Data Export token, and a token maps to exactly one project. If you manage several Clarity projects you end up editing the config and restarting the client every time you switch project.

This proxy keeps a name → token map and resolves the token by name at runtime. It does not reimplement any Clarity functionality: it launches the official server as a child process and forwards calls to it, so it inherits the full tool set and tracks upstream changes automatically.

Related MCP server: MCP OAuth Proxy

How it works

The package acts as a server towards its MCP client (Claude, Cursor, …) and as a client towards the official server at the same time. It registers two tools of its own and re-exports whatever the official server exposes. A call that isn't one of its own tools is forwarded to the child process and the response is returned unchanged.

Selecting a client with clarity_usa_cliente restarts the child with that client's token. The token is read from the registry on the server side and is never sent through the conversation.

The child is launched as @microsoft/clarity-mcp-server@latest, so upstream releases are picked up without changes here.

Configuration

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "clarity-mcp-multi@latest"],
      "env": {
        "CLARITY_TOKENS": "{\"acme\":\"<token>\",\"globex\":\"<token>\"}"
      }
    }
  }
}

CLARITY_TOKENS is a JSON object mapping a client name to its Clarity Data Export token (Clarity → Settings → Data export). As an alternative, set CLARITY_TOKENS_FILE to a path holding the same JSON. CLARITY_DEFAULT_CLIENT optionally sets the client selected at startup.

Keep tokens out of source control: pass them through the environment or a file the host loads, not in a committed config.

Tools

Tool	Description
`clarity_clienti`	Lists the configured client names and the active one. No token is returned.
`clarity_usa_cliente`	Sets the active client by name; subsequent calls use its token.

Names are matched case-insensitively. Every other tool is proxied to the official server under the active client's token.

Requirements

Node.js 18 or later. One Clarity Data Export token per project.

License

MIT

Available Tools

5 tools

clarity_clientiA

Elenca i clienti Clarity configurati (solo nomi) e qual è quello attivo. Nessun token esposto.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that only names are returned, the active one is indicated, and no tokens are exposed. For a simple read-only list, this is transparent, though it could mention behavior if no clients configured.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words, action verb upfront, and all information is relevant. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description provides sufficient information: it lists names and active client, with a safety note. It could be slightly more explicit about the output format, but is adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so baseline is 4. No additional parameter information is needed, and the description does not need to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists configured Clarity clients (only names) and indicates which is active, with a safety note about no token exposure. It distinguishes from sibling tools like 'clarity_usa_cliente' (likely for selecting a client) by focusing on listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for checking active client and all configured clients, but does not explicitly state when to use versus alternatives like 'clarity_usa_cliente' or when not to use. Context is clear but lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clarity_usa_clienteA

Imposta il cliente Clarity attivo passando SOLO il nome: il server usa il token corrispondente dal registro (il token non passa dalla chat). Chiamalo prima di leggere i dati quando lavori su un cliente specifico.

ParametersJSON Schema

Name	Required	Description	Default
`cliente`	Yes	Nome del cliente, come configurato in CLARITY_TOKENS.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full burden. It explains that the token does not pass through the chat and that the server uses a registry token, but lacks details on side effects like overriding previous client settings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the purpose and usage context, with every phrase earning its place. No unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description covers purpose, usage timing, and a security aspect. It is mostly complete, though it could mention error behavior if the client name is invalid.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the parameter (name as configured in CLARITY_TOKENS). The description adds minimal extra meaning, just reiterating that only the name is passed and token security. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sets the active Clarity client by passing only the name, which distinguishes it from sibling tools like 'clarity_clienti' that likely list clients.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to call this tool before reading data when working on a specific client, providing clear context for when to use it, though it does not name alternatives or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-session-recordingsA

Read-only

List Microsoft Clarity session recordings based on specified filters. The filters allow you to narrow down the recordings by various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.

ParametersJSON Schema

Name	Required	Description	Default
`count`	No	The number of sample session recordings to return. Default is 100. Maximum is 250.
`sortBy`	No	Sort option for session recordings. Default is SessionStart_DESC (newest first).	SessionStart_DESC
`filters`	Yes	A set of filters that can be applied to the Microsoft Clarity to session recordings. This allows you to filter recordings based on various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context by detailing that it lists recordings based on filters and specifies the required date filter format. No contradiction with annotations. Could mention pagination or rate limits, but the schema covers return structure partially.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, concise and front-loaded with the core purpose. No wasted words, and it efficiently communicates the tool's function and key constraint (date format).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many filters, nested objects) and the absence of an output schema, the description should explain what the listing returns. It does not mention return format or pagination details beyond the count parameter. This gap reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already provides detailed parameter meanings. The description adds minimal extra value beyond a brief overview of filter capabilities. For a tool with such rich schema descriptions, this is adequate but not exceptional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'Microsoft Clarity session recordings', with explicit mention of filtering. The tool name and description distinguish it from sibling tools like 'clarity_clienti' and 'query-analytics-dashboard'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates when to use the tool (to list recordings with filters) and highlights the required date filter format. However, it does not provide explicit guidance on when not to use it or mention alternatives, which would improve score further.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query-analytics-dashboardA

Read-only

Fetch Microsoft Clarity analytics data using a simplified natural language search query. The query should be focused on one specific data retrieval or aggregation task. Avoid complex multi-purpose queries. Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	A natural language search query string for filtering and shaping analytics data. The query should be specific and include temporal constraints when available. (e.g., 'Top browsers last 3 days', 'The active time duration for mobile devices in United States last week'). Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint true and destructiveHint false, so safety is clear. The description adds behavioral context about natural language querying and prompting for time ranges, which goes beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two focused sentences plus a short note. Information is front-loaded and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description covers the core behavior and usage guidance adequately. It does not detail return format or error handling, but these are less critical for a natural language query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter description in the schema largely mirrors the tool description. The description adds minimal extra meaning beyond what the schema already provides, so it meets but does not exceed the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches Microsoft Clarity analytics data using a natural language query. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like clarity_clienti or list-session-recordings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance to focus on one task, avoid complex multi-purpose queries, and specify time ranges. It also instructs to prompt the user if no time range is provided, indicating appropriate usage context. However, it does not compare to alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query-documentation-resourcesA

Read-only

Retrieve Microsoft Clarity documentation snippets for finding answers to user questions including step-by-step screenshots for setup guides, features, usage, troubleshooting, and integration instructions. The query should be focused on one specific documentation topic or question. Avoid complex multi-purpose queries.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	A natural language search query string for filtering and shaping analytics data. The query should be specific and include temporal constraints when available. (e.g., 'Top browsers last 3 days', 'The active time duration for mobile devices in United States last week'). Time ranges should be explicitly specified when possible. If no time range is provided, prompt the user to specify one.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds context about the content returned (snippets, screenshots) but does not disclose additional behavioral traits like pagination, rate limits, or response structure beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core purpose and immediately follows with usage guidance. Every word earns its place, with no redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only tool with one parameter and no output schema, the description adequately covers purpose, query guidance, and safety. It could optionally mention the expected return format (e.g., text snippets), but given the annotations and simplicity, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'query' has 100% schema description coverage with a detailed description including examples and guidance for temporal constraints. The description adds value by providing concrete examples and instructing the user to prompt for missing time ranges, exceeding what the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves Microsoft Clarity documentation snippets for answering user questions, including specific content types like step-by-step screenshots for setup, features, and troubleshooting. It distinguishes well from sibling tools like query-analytics-dashboard and list-session-recordings, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some guidance: queries should be focused on one specific topic and avoid complexity. However, it does not explicitly state when to use this tool versus alternatives, nor does it specify prerequisites or cases where the tool is not appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv0.1.0Jun 29, 2026
- First observedclarity_clienti
- First observedclarity_usa_cliente
- First observedlist-session-recordings
- First observedquery-analytics-dashboard
- First observedquery-documentation-resources

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-06-29 11:15 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: client management (list/set active) vs. data retrieval (session recordings, analytics queries, documentation). No overlap.

Naming Consistency2/5

Tools are named in two languages (Italian and English) and use different conventions: clarity_clienti and clarity_usa_cliente use snake_case and Italian, while the others use hyphens and English. This inconsistency can confuse agents.

Tool Count4/5

5 tools is a reasonable number for a Clarity-focused server, covering client selection, recordings, analytics, and documentation without being excessive.

Completeness3/5

Covers core workflows (client management, listing recordings, analytics queries, documentation) but lacks detailed session drill-down or export capabilities, which are notable gaps.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

OneDroid SynapseOAuth
ai.onedroid
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Security Observability
1
QuallaaOAuth
com.quallaa
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
AI & Machine Learning Communication
2
TokenOracle
com.guffeyholdings
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Finance Monitoring
2
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

Collaborative MCP Proxy Server
Agent Orchestration AI & Machine Learning
junteakim
F
license
Not graded
quality
D
maintenance
Enables multi-AI collaborative analysis by proxying requests to existing login-based MCP servers (Gemini CLI and Codex CLI) from Claude Desktop or Claude Code.
Updated a year ago (2025-08-17 11:50 UTC)
-
MCP OAuth Proxy
Security Developer Tools
SunilAngadala
A
license
Not graded
quality
B
maintenance
Acts as a secure OAuth 2.0/2.1 proxy gateway for MCP servers, enabling integration with Claude and ChatGPT platforms.
Updated 3 months ago (2026-06-27 20:13 UTC)
19 npm
MIT
janusmcp
Developer Tools Security
Bayway
A
license
Not graded
quality
A
maintenance
Local, open-source multi-account MCP broker — one endpoint, every account. Add credentials once and switch identity without reconnecting, from any LLM client.
Updated 4 days ago (2026-09-12 06:02 UTC)
9
MIT
mcpfold
Developer Tools Agent Orchestration
dj-pearson
F
license
Not graded
quality
B
maintenance
Local-first CLI + proxy that curates your MCP servers per client from one canonical config, cutting tool-schema tokens ~80% and resolving secret references instead of hardcoding keys.
Updated 6 days ago (2026-09-10 02:54 UTC)
-