How to Use the Hotjar (Behavior Analytics) MCP in Pydantic AI

Q: How do I configure Hotjar (Behavior Analytics) with Pydantic AI?

Run pip install pydantic-ai-slimmcp. Initialize the connection using MCPToolset with your HTTP endpoint, and pass it to the toolsets array in your Agent definition.

Q: Will Pydantic AI catch missing fields in Hotjar (Behavior Analytics) heatmaps?

It fails immediately. If getheatmap returns an incomplete matrix, the framework throws a validation error. Your agent stops before making any decisions based on partial data.

Q: How does the server protect the raw text inside feedback widgets?

When your agent requests data via listfeedback, the V8 Isolate Sandbox processes the request ephemerally. The system holds no persistent state, meaning user comments exist only during the active HTTP stream.

Strictly type-check your user behavior data using Pydantic AI and our managed MCP connection.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Hotjar (Behavior Analytics) MCP to Pydantic AI

Create your Vinkius account to connect Hotjar (Behavior Analytics) to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Hotjar (Behavior Analytics) with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Validate session metadata with Pydantic AI

The `list_recordings` tool returns complex JSON structures detailing user clicks and navigation paths. Your agent calls `get_site` to verify the domain ID, then pulls the corresponding session data. Pydantic AI validates every field against your predefined schema at runtime. If the API changes the timestamp format or drops a critical field, the framework fails loudly. You get a strict validation error instead of silent data corruption. Your agent refuses to process malformed behavioral data, keeping your analytics database clean.

Type-safe click density extraction

Running `list_heatmaps` grabs the index of all available visual reports. When your agent drills down using `get_heatmap`, it expects an exact coordinate matrix. Pydantic guarantees the payload matches your expected integer arrays before the model even sees it. This model-agnostic approach means you switch between Claude, Gemini, or local models without rewriting your parsing logic. The MCP framework handles the extraction, and Pydantic ensures the LLM receives perfectly structured heatmap coordinates every single time.

Enforce schemas on Hotjar MCP Server data

The `list_funnels` tool outputs step-by-step conversion metrics, while `list_feedback` pulls unstructured widget comments. Your agent combines these to figure out exactly what users say right before they abandon a purchase. Unstructured feedback usually breaks automated pipelines. Pydantic AI forces the agent to map the raw text from the feedback widget into your strict internal models. If the agent hallucinates a missing funnel step, the runtime catches the error and halts the execution.

Setup guide

Set up Hotjar (Behavior Analytics) MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "hotjar-behavior-analytics-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Hotjar (Behavior Analytics) tools.",
)

result = await agent.run("List recent Hotjar (Behavior Analytics) transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Hotjar. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Hotjar (Behavior Analytics) now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Hotjar (Behavior Analytics) MCP in Pydantic AI

Run pip install pydantic-ai-slim[mcp]. Initialize the connection using MCPToolset with your HTTP endpoint, and pass it to the toolsets array in your Agent definition.

It fails immediately. If get_heatmap returns an incomplete matrix, the framework throws a validation error. Your agent stops before making any decisions based on partial data.

Yes. Pydantic AI is completely model-agnostic. You route list_surveys data to a local Llama 3 instance just as easily as you send it to GPT-4.

The framework supports both Streamable HTTP and SSE transports. You pass the unified MCPToolset class your Vinkius URL, and it negotiates the connection automatically.

When your agent requests data via list_feedback, the V8 Isolate Sandbox processes the request ephemerally. The system holds no persistent state, meaning user comments exist only during the active HTTP stream.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript