---
title: "Connect Hotjar to Claude: Manage Survey Designs and Responses"
slug: connect-hotjar-to-claude-manage-survey-designs-and-responses
date: 2026-11-04
author: Sidharth Verma
categories: ["AI & Agents"]
excerpt: "Learn how to build a robust Hotjar MCP server to connect Claude to your survey and feedback data. Execute user lookups, analyze UX sentiment, and automate GDPR DSAR workflows natively."
tldr: "A technical guide to connecting Hotjar to Claude via Truto's managed MCP servers. Learn how to generate dynamic tools to analyze survey responses, execute user lookups, and configure secure data boundaries."
canonical: https://truto.one/blog/connect-hotjar-to-claude-manage-survey-designs-and-responses/
---

# 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](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). 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](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), or use a [managed integration platform](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) 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](https://truto.one/connect-hotjar-to-chatgpt-analyze-surveys-and-user-feedback/) or explore our broader architectural overview on [connecting Hotjar to AI Agents](https://truto.one/connect-hotjar-to-ai-agents-automate-survey-data-and-privacy/).

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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/), connect it natively to Claude Desktop, and execute complex user research workflows using natural language.

> Want to give your AI agents secure, authenticated access to Hotjar and 100+ other SaaS APIs? Let's talk about [managed MCP architecture](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/).
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the Hotjar API

A custom MCP server is [a self-hosted integration layer](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/). 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.

```bash
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.

```json
{
  "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:

```json
{
  "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](https://truto.one/integrations/detail/hotjar).

## 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.

```mermaid
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.