Connect Hotjar to Claude: Manage Survey Designs and Responses

If you need to connect Hotjar to Claude to automate user experience research, analyze qualitative survey responses, or orchestrate GDPR compliance data deletions, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Hotjar's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Hotjar to ChatGPT or explore our broader architectural overview on connecting Hotjar to AI Agents.

Giving a Large Language Model (LLM) read and write access to a user sentiment and behavioral analytics platform like Hotjar is an engineering challenge. You have to handle API token lifecycles, map nested JSON schemas for survey structures to MCP tool definitions, and deal with Hotjar's organization and site-level isolation. Every time Hotjar updates an endpoint or changes a survey payload structure, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Hotjar, connect it natively to Claude Desktop, and execute complex user research workflows using natural language.

The Engineering Reality of the Hotjar API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Hotjar's specific API quirks is painful. You are not just integrating "Hotjar" - you are integrating a highly compartmentalized system of Organizations, Sites, and Surveys, heavily restricted by modern privacy laws.

If you decide to build a custom MCP server for Hotjar, here are the specific integration challenges you will face:

Hierarchical Data Isolation Hotjar's data model strictly separates data across the Organization and Site levels. Endpoints for surveys and responses require a site_id, while privacy operations like user lookups operate at the organization_id level. An LLM has no inherent context on this hierarchy. If you build a custom integration, you must explicitly define these dependencies in your JSON schemas and tool descriptions, ensuring Claude knows exactly which ID to pass for which operation, otherwise every request will fail with a 404 or 403 error.

Complex Nested Survey Schemas Survey responses in Hotjar are not flat key-value pairs. They contain nested objects detailing the user's browser, operating system, window size, user attributes, and a complex answers array mapping back to specific question IDs. Analyzing this data requires fetching the survey definition first, parsing the questions array, and then mapping those question IDs to the answers provided in the survey response payload. An LLM needs explicit instructions and well-structured schemas to navigate these relational hops natively.

Asynchronous Privacy Operations Operations like the Data Subject Access Request (DSAR) user lookup do not return immediate synchronous data. When you submit a request to create_a_hotjar_user_lookup, Hotjar returns an empty 202 Accepted response. The actual data deletion or report generation happens asynchronously via email to the data subject. Your MCP tools must clearly explain this asynchronous behavior in their descriptions so the LLM does not hallucinate expected return data or get confused by an empty response body.

Rate Limits and Retry Logic Hotjar enforces strict rate limits across its endpoints. When building integrations, developers often mistakenly assume their integration platform will magically absorb rate limit errors. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (or the orchestration framework driving the LLM) is strictly responsible for implementing retry and backoff logic.

How to Create the Hotjar MCP Server

Truto dynamically generates MCP tools from the underlying API documentation and schemas. You can generate a self-contained, authenticated MCP server URL for Hotjar in two ways.

Method 1: Via the Truto UI

For one-off agent setups or internal IT workflows, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to your connected Hotjar Integrated Account page.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server settings (assign a descriptive name, select allowed methods like read or write, and set an optional expiration date).
5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the API

For programmatic provisioning - such as generating temporary MCP servers for dynamic cloud agents - you can use the Truto REST API. This POST request requires your standard Truto API token.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hotjar UX Research Agent",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates that the Hotjar integration has available tools, generates a cryptographically secure token, and returns a ready-to-use URL.

{
  "id": "mcp-789-hotjar",
  "name": "Hotjar UX Research Agent",
  "config": {
    "methods": ["read", "write"]
  },
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6...",
  "expires_at": "2026-12-31T23:59:59Z"
}

This single URL contains everything the client needs to discover tools and execute authenticated requests against Hotjar.

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude environment. All communication happens over HTTP POST using JSON-RPC 2.0.

Method A: Via the Claude UI

If you are using Claude's web interface or enterprise team spaces (and have the appropriate feature flags or account tier enabled):

1. In Claude, navigate to Settings -> Integrations -> Add MCP Server.
2. Give your server a name (e.g., "Hotjar Research Data").
3. Paste the Truto MCP server URL you generated earlier.
4. Click Add. Claude will instantly send an initialize request to discover the available Hotjar tools.

Method B: Via Manual Config File (Claude Desktop)

If you are running Claude Desktop locally or configuring a headless agent environment, you must map the URL in your claude_desktop_config.json file. Because Truto uses standard Server-Sent Events (SSE) over HTTP, you will use the @modelcontextprotocol/server-sse transport wrapper.

Locate your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration block:

{
  "mcpServers": {
    "hotjar-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The application will read this configuration, connect to the Truto URL, and dynamically load the Hotjar tools into the model's context window.

Core Hero Tools for Hotjar

When Claude connects to the server, Truto dynamically builds tool definitions based on Hotjar's API schemas. Here are the core hero tools available for orchestration.

list_all_hotjar_surveys

This read-only tool retrieves all surveys associated with a specific Hotjar site. It returns critical metadata, including the survey id, name, type, is_enabled status, and whether sentiment_analysis_enabled is active. It also returns the full array of questions configured for each survey.

Usage Notes: You must provide a valid site_id. The response handles up to 100 surveys per page. Claude can use this to map human-readable survey names to the internal IDs required for fetching response data.

"List all active surveys for Hotjar site ID 123456. Filter out the disabled ones, and tell me how many total questions are in the 'Onboarding Feedback' survey."

get_single_hotjar_survey_by_id

When Claude needs deep context on a specific survey structure before analyzing answers, it calls this tool. It returns the complete definition of a single survey, explicitly including the questions array.

Usage Notes: Requires both site_id and id (the survey ID). This is a critical prerequisite step for complex analysis because survey responses only provide question IDs, not the question text itself. The LLM needs this map to make sense of the answers.

"Get the details for survey ID 98765 on site 123456. I need the exact text of every question asked in this survey so I can map them to the raw response data."

list_all_hotjar_survey_responses

This tool extracts the actual user feedback. It lists responses for a specific survey, sorted newest first. The returned objects contain the answers array, user metadata (browser, OS, device, country, window size), the response_origin_url, and the recording_url if session recording was active.

Usage Notes: Requires site_id and survey_id. For large datasets, the LLM must utilize the next_cursor logic embedded in the schema to paginate through thousands of responses.

"Fetch the latest 50 responses for the 'Checkout Abandonment' survey (ID 98765) on site 123456. Summarize the most common issues reported by users on mobile devices."

create_a_hotjar_user_lookup

This write operation executes a GDPR/CCPA data subject user lookup. It instructs Hotjar to locate a user across all site data based on their email or a custom user ID map.

Usage Notes: Requires the organization_id. The payload must contain either data_subject_email or a data_subject_site_id_to_user_id_map. If delete_all_hits is set to false, Hotjar emails a data report to the subject. If set to true, it permanently deletes their data. It returns an empty 202 Accepted response.

"Execute a data deletion request for the email privacy@example.com across organization ID 445566. Ensure delete_all_hits is set to true to comply with this GDPR request."

For the complete schema definitions and a full inventory of available endpoints, visit the Hotjar integration page.

Workflows in Action

Connecting Hotjar to Claude unlocks agentic workflows that replace hours of manual CSV exports and spreadsheet pivot tables. Here are two real-world sequences.

Automated UX Sentiment Synthesis

Product managers often drown in raw text responses from NPS or feature-feedback surveys. An AI agent can pull this data, map it to the actual questions, and generate a synthesized executive summary.

"Pull the latest responses from the 'New Dashboard Feedback' survey on site 123456. Map the answers to the actual question text, isolate responses from macOS users, and summarize the top three complaints about navigation."

Execution Steps:

1. Claude calls get_single_hotjar_survey_by_id to retrieve the questions array and caches the mapping of Question IDs to actual text.
2. Claude calls list_all_hotjar_survey_responses to pull the latest batch of answers.
3. Claude filters the returned JSON in memory, looking only at objects where os contains "macOS".
4. The agent cross-references the answers array against the question text, analyzes the sentiment, and outputs a formatted markdown summary to the user.

sequenceDiagram
    participant PM as Product Manager
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Hotjar as Hotjar API

    PM->>Claude: Summarize dashboard feedback for macOS users
    Claude->>Truto: Call get_single_hotjar_survey_by_id
    Truto->>Hotjar: GET /v1/sites/123456/surveys/98765
    Hotjar-->>Truto: Survey Schema & Questions
    Truto-->>Claude: JSON Tool Result
    Claude->>Truto: Call list_all_hotjar_survey_responses
    Truto->>Hotjar: GET /v1/sites/123456/surveys/98765/responses
    Hotjar-->>Truto: Raw Response Array
    Truto-->>Claude: JSON Tool Result
    Claude->>Claude: Filter by OS, synthesize text
    Claude-->>PM: Formatted UX Report

Zero-Touch GDPR Data Subject Deletion

Privacy regulations require rapid fulfillment of data deletion requests. Instead of a human manually logging into the Hotjar dashboard, an IT operations agent can execute the request securely via chat.

"We received a Right to be Forgotten request from user alex.smith@example.com. Please initiate a full data deletion for this email across our Hotjar organization (ID 445566)."

Execution Steps:

1. Claude constructs the payload for create_a_hotjar_user_lookup, setting organization_id to 445566, data_subject_email to the provided email, and strictly setting delete_all_hits: true.
2. Claude fires the tool call to the Truto MCP server.
3. Truto proxies the request to Hotjar.
4. Hotjar returns a 202 Accepted status.
5. Claude informs the IT admin that the asynchronous deletion process has been successfully initiated.

Security and Access Control

When passing B2B behavioral data and privacy controls to an LLM, security is critical. Truto MCP servers provide strict, configurable boundaries that ensure Claude only accesses what you explicitly authorize.

• Method Filtering: Use config.methods to restrict the MCP server entirely to ["read"] operations. This ensures Claude can analyze survey responses but cannot accidentally trigger user deletions.
• Tag Filtering: Limit the server scope using config.tags. If you tag specific Hotjar resources with ["surveys"], the generated MCP URL will only expose tools related to surveys, hiding other administrative operations.
• API Token Authentication: By default, possessing the MCP URL grants access. By enabling require_api_token_auth: true, Truto forces the client to pass a valid Truto API session token in the authorization header, preventing unauthorized local access.
• Auto-Expiring Servers: Use the expires_at attribute to generate temporary MCP servers. Once the timestamp passes, Truto automatically schedules a cleanup task to purge the token, instantly revoking the LLM's access.

Scale Your AI Agent Integrations

Building a custom MCP server for Hotjar requires mapping complex hierarchical models, standardizing pagination, and building resilient schemas for LLM consumption. By using Truto to generate managed MCP servers, you shift the burden of API maintenance, documentation parsing, and schema generation off your engineering team. Your agents get immediate, secure access to Hotjar data, allowing you to focus on building intelligent UX analysis workflows instead of writing integration boilerplate.