CUT Clarity MCP Server

cut-clarity-mcp-server is a small, deployable, read-only Model Context Protocol server for exposing Microsoft Clarity export data to ChatGPT Agent Builder.

The intended architecture is:

ChatGPT Agent Builder
-> your public MCP server URL
-> Microsoft Clarity API/export data

This is intentionally separate from the WordPress plugin AI Laser Studio. Do not put this server inside WordPress, and do not point ChatGPT Agent Builder at WordPress for Clarity data. WordPress can later show status or link to this external MCP server, but secrets and analytics middleware stay outside WordPress.

What It Exposes

The server registers five MCP tools:

• list_available_exports

• get_project_live_insights

• export_project_summary

• export_page_metrics

• export_event_metrics

All tools are read-only. There are no write, mutation, CRUD, or frontend features.

Microsoft Clarity endpoint paths are centralized in src/config/clarityEndpoints.ts. The server uses the confirmed Microsoft Clarity Data Export API endpoint:

GET https://www.clarity.ms/export-data/api/v1/project-live-insights

Clarity's Data Export API supports numOfDays=1, 2, or 3; it does not support arbitrary historical date ranges. Tools that accept start_date and end_date convert ranges ending today into numOfDays. Unsupported historical ranges return a structured unsupported_date_range error instead of pretending to fetch data.

Related MCP server: Search Console MCP

Transport

This project uses the official/broadly used Node MCP SDK package @modelcontextprotocol/sdk.

The remote transport endpoint is:

/mcp

Use your own deployed MCP server URL in ChatGPT Agent Builder, for example:

https://cut-clarity-mcp.your-domain.com/mcp

Do not enter https://www.clarity.ms in ChatGPT Agent Builder. ChatGPT Agent Builder should call your MCP server, and this server calls Clarity server-side with the Bearer token.

Environment Variables

Copy .env.example to .env for local development.

npm install
cp .env.example .env
npm run dev

Variables:

• PORT: local/server port, default 3000

• NODE_ENV: development or production

• CLARITY_API_TOKEN: Microsoft Clarity Bearer token

• CLARITY_BASE_URL: defaults to https://www.clarity.ms

• CLARITY_HTTP_TIMEOUT_MS: timeout for each upstream Clarity HTTP request, default 15000

• MCP_TOOL_TIMEOUT_MS: hard timeout for each MCP tool call, default 20000

• MCP_TOP_PAGES_LIMIT: maximum page rows returned to the MCP client, default 25

• MCP_TOP_SIGNALS_LIMIT: maximum signal/friction rows returned to the MCP client, default 25

• MCP_SAMPLE_ROWS_LIMIT: maximum sample rows returned to the MCP client, default 10

• MCP_INCLUDE_RAW_DEFAULT: whether bounded raw samples are included by default, default false

• MCP_MAX_RESPONSE_MODE: response mode, currently compact

• DEFAULT_PROJECT_ID: optional fallback project id for tool calls

• DEFAULT_TIMEZONE: defaults to Europe/Amsterdam

• LOG_LEVEL: debug, info, warn, or error

• MCP_SERVER_API_KEY: optional auth key for MCP requests

No secrets are committed. Tokens are only read from environment variables and are never returned in tool responses or logs.

Optional MCP Server Auth

If MCP_SERVER_API_KEY is set, every request to /mcp must include:

Authorization: Bearer <MCP_SERVER_API_KEY>

GET /health remains public, but only returns boolean configuration status. If your ChatGPT Agent Builder setup cannot send an extra Authorization header, leave MCP_SERVER_API_KEY empty and avoid broadly sharing the MCP URL. The Clarity token still remains server-side.

Local Development

npm install
cp .env.example .env
npm run dev

Health check:

curl http://localhost:3000/health

MCP endpoint:

http://localhost:3000/mcp

Production build:

npm run build
npm start

Typecheck and smoke tests:

npm run typecheck
npm test
npm run smoke-test

Health Check

GET /health returns:

{
  "ok": true,
  "service": "cut-clarity-mcp-server",
  "version": "0.1.0",
  "clarity_configured": true,
  "default_project_configured": true
}

The health endpoint does not call Microsoft Clarity. It is intentionally fast and does not expose secrets.

Clarity Endpoint Configuration

Endpoint strings are defined only in src/config/clarityEndpoints.ts.

Each endpoint has:

• enabled

• path

• method

• confirmed

• note

The current mappings are:

• get_project_live_insights: confirmed endpoint with numOfDays=1

• export_project_summary: confirmed endpoint without dimensions

• export_page_metrics: confirmed endpoint with dimension1=URL

• export_event_metrics: confirmed endpoint with dimension1=URL, normalized for friction metrics

Endpoint strings should not be scattered through the codebase. If Microsoft adds more granular export endpoints later, update this single file and the matching tool handler.

Compact MCP Responses

The server fetches the full Clarity response from Microsoft and keeps it in memory long enough to normalize, aggregate, and build top lists. The default MCP response sent back to ChatGPT Agent Builder is compact and does not include full raw arrays.

Default tool responses include:

• tool

• project_id

• period when applicable

• row_count

• summary

• top rows such as top_pages, top_signals, or top_friction_pages

• sample_rows

• raw_retained: true

• raw_included: false

• warnings such as raw_not_included, limited_to_top_n, and sample_rows_limited

Every tool accepts optional include_raw: true. Even then, the server returns only a bounded raw_sample, not an uncontrolled multi-megabyte raw export. Full raw payloads are never logged.

Local Tool Smoke Checks

Run static checks and unit smoke tests:

npm run typecheck
npm test
npm run smoke-test

npm run smoke-test calls each MCP tool handler with the local environment and prints a compact table with status, duration_ms, and any structured error_code. It is designed to prove tools return quickly. If DEFAULT_PROJECT_ID or CLARITY_API_TOKEN is missing, the smoke test should show structured errors such as missing_project_id or missing_clarity_token, not hang.

When Clarity does not respond within CLARITY_HTTP_TIMEOUT_MS, tools return:

{
  "ok": false,
  "error": {
    "code": "clarity_upstream_timeout",
    "message": "The Clarity API did not respond within 15000 ms",
    "status": 504
  }
}

To verify the deployed service is configured:

curl https://your-cloud-run-url/health

Expected:

{
  "ok": true,
  "clarity_configured": true,
  "default_project_configured": true
}

In ChatGPT Agent Builder, call list_available_exports first. It should show configured and confirmed exports, not placeholder not_configured mappings.

Deployment: Railway

1. Push this repository to GitHub.

2. Create a Railway project from the GitHub repo.

3. Set environment variables in Railway:

   • CLARITY_API_TOKEN

   • CLARITY_BASE_URL

   • DEFAULT_PROJECT_ID if desired

   • DEFAULT_TIMEZONE

   • MCP_SERVER_API_KEY if your MCP client supports it

4. Use start command:

npm start

5. Use the public Railway URL plus /mcp in ChatGPT Agent Builder.

Deployment: Render

1. Create a Render Web Service.

2. Use build command:

npm install && npm run build

3. Use start command:

npm start

4. Set the same environment variables listed above.

5. Use the public Render URL plus /mcp in ChatGPT Agent Builder.

render.yaml is included as a starting point. It does not contain secrets.

Deployment: Google Cloud Run

Build and push an image:

gcloud builds submit --tag gcr.io/PROJECT_ID/cut-clarity-mcp-server

Deploy:

gcloud run deploy cut-clarity-mcp-server \
  --source . \
  --region europe-west1 \
  --allow-unauthenticated \
  --set-env-vars NODE_ENV=production,CLARITY_BASE_URL=https://www.clarity.ms,CLARITY_HTTP_TIMEOUT_MS=15000,MCP_TOOL_TIMEOUT_MS=20000,MCP_TOP_PAGES_LIMIT=25,MCP_TOP_SIGNALS_LIMIT=25,MCP_SAMPLE_ROWS_LIMIT=10,MCP_INCLUDE_RAW_DEFAULT=false,MCP_MAX_RESPONSE_MODE=compact,DEFAULT_TIMEZONE=Europe/Amsterdam,DEFAULT_PROJECT_ID=YOUR_CLARITY_PROJECT_ID

Do not pass PORT as an environment variable on Cloud Run; Cloud Run reserves and sets it automatically. Set CLARITY_API_TOKEN and optional MCP_SERVER_API_KEY with Google Cloud Secret Manager or your preferred Cloud Run secret workflow.

Use:

https://your-cloud-run-url/mcp

in ChatGPT Agent Builder.

Safety Notes

• All MCP tools are read-only.

• Authorization headers and tokens are never logged.

• Raw Clarity payloads can be returned by tools, but environment secrets are not included.

• Logs contain only safe metadata such as tool name, project id, dates, status-like metadata, row count, and duration.

• Inputs are validated with zod plus explicit date range checks.

• Requests to Clarity use a timeout, limited retries, and exponential backoff for 429 and 5xx failures.