How to Use the Heap MCP in Pydantic AI

Q: What happens if the Heap MCP server returns bad data to my Pydantic AI agent?

Your agent will throw a ValidationError immediately. This is the core benefit—it prevents corrupted or unexpected data from propagating through your system, ensuring your agent acts on reliable information.

Q: How do I add user properties to Heap with a Pydantic AI agent?

Your agent calls the adduserproperties tool. Pydantic AI helps you ensure the properties you send are correctly formatted, and it validates the response from Heap to confirm the operation succeeded.

Add type-safe Heap analytics to any agent. Pydantic AI validates every API call so your data is always correct and never silent.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Heap MCP to Pydantic AI

Create your Vinkius account to connect Heap 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 Heap with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Track Events Without Silent Failures

When your agent calls `track_event` or `identify_user`, you need to know it worked. Pydantic AI wraps the Heap MCP tools in models, so if the API call fails or returns an unexpected status, your code gets a `ValidationError`. No more guessing if your analytics data is actually being recorded. This works with any LLM—OpenAI, Anthropic, local models, you name it. Your agent's logic for tracking events is completely separate from the underlying model. The only thing that matters is that the data passed to tools like `track_event` is correct.

Query User Data with Guaranteed Structure

Stop writing boilerplate code to parse API responses. When your agent uses `query_user_profiles`, Pydantic AI automatically validates the returned data against a model. If a user profile is missing a field or has the wrong data type, your agent knows immediately. The same principle applies to `get_segments` and `get_event_definitions`. You get back clean, structured Python objects. This prevents your agent from hallucinating data structures or making decisions based on corrupted information. It's about correctness, first and foremost.

Manage Properties with Pydantic AI's Type Safety

Updating user data should be a safe operation. With this MCP server, your Pydantic AI agent can use `add_user_properties` to modify a user's profile. You can define a Pydantic model for the properties, and the framework ensures what you're sending is valid. This approach works for single updates or in batches with `bulk_add_user_properties`. It forces you to be explicit about your data schema. If you try to add a property that doesn't fit the expected format, you'll get an error before the bad data ever reaches Heap.

Setup guide

Set up Heap 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": {
        "heap-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

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

result = await agent.run("List recent Heap 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 Heap. 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 Heap 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 Heap MCP in Pydantic AI

Every response from the Heap server is parsed and validated against a Pydantic model at runtime. If the data doesn't match the expected schema, it raises a `ValidationError` instead of failing silently.

Yes. Pydantic AI is model-agnostic. You can use it with models from OpenAI, Anthropic, Google, or even local models to call tools like `track_event`.

Your agent will throw a `ValidationError` immediately. This is the core benefit—it prevents corrupted or unexpected data from propagating through your system, ensuring your agent acts on reliable information.

Your agent calls the `add_user_properties` tool. Pydantic AI helps you ensure the properties you send are correctly formatted, and it validates the response from Heap to confirm the operation succeeded.

The connection gives your agent access to your Heap user profiles and their associated properties. Vinkius ensures security by handling authentication through a single token and running every tool call in a zero-trust, ephemeral environment that is destroyed after execution.

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