How to Use the Heap MCP in OpenAI Agents SDK

Q: How do I connect the Heap MCP Server to the OpenAI Agents SDK?

You just need the Vinkius endpoint URL. Instantiate MCPServerStreamableHttp with the URL and pass it to your Agent constructor. The tools are discovered automatically.

Q: Can my OpenAI Agent handle bulk event tracking in Heap?

Yes. The agent can use the bulktrackevents and bulkadduserproperties tools. This is the best approach for high-throughput applications to avoid API rate limits.

Q: Can I query user profiles from Heap with an OpenAI Agent?

Absolutely. The queryuserprofiles tool lets your agent find users based on specific properties. The agent can then use that information to make decisions or update other systems.

Connect your OpenAI Agent to Heap. Get production-ready analytics with built-in safety guardrails and full tracing.

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 OpenAI Agents SDK

Create your Vinkius account to connect Heap to OpenAI Agents SDK 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 OpenAI Agents SDK

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Track Events with Guardrails

Your agent can track user actions and tie them to a specific identity. Use `track_event` for sign-ups, purchases, or any other critical signal. Then, link that activity to a known user with `identify_user`. The OpenAI SDK's guardrails give you a chance to review the agent's plan before it sends the data. This isn't just for one-off events. You can build specialized agents that hand off tasks. For example, one agent could handle user registration while another tracks engagement, all logged in your OpenAI dashboard. You see exactly which agent called `track_event` and why.

Manage Users at Production Scale

When you're dealing with high traffic, individual API calls create too much overhead. This MCP Server exposes `bulk_track_events` so your agent can batch analytics signals. It's the right way to handle thousands of events without bogging down your app. The same goes for user data. Instead of updating profiles one by one, your agent can use `bulk_add_user_properties` to modify multiple users at once. It's a clean, efficient way to sync data from your system into Heap.

Automate Data Compliance with Your MCP Server

Build agents that handle data privacy requests automatically. The `delete_user_data` tool lets an agent permanently remove a user and their history from Heap, helping you meet GDPR and other compliance rules. You can trigger this from an internal admin panel or a customer support chat. You can also create agents that act as internal auditors. Give them access to `query_user_profiles` to find specific cohorts or `get_api_usage` to monitor your project's health. It's a reliable way to keep an eye on your analytics setup without manual checks.

Setup guide

Set up Heap MCP in OpenAI Agents SDK

Prerequisites

Python 3.10+ installed
openai-agents package (pip install openai-agents)
Active Vinkius subscription with a valid endpoint token

1

Install the SDK

Run pip install openai-agents to install the OpenAI Agents SDK. The MCP integration is built-in — no extra dependencies needed.
2

Connect via SSE transport

Use MCPServerSse with your Vinkius endpoint URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. The SDK auto-discovers all Heap tools at runtime.
3

Create your Agent

Pass the MCP to Agent(mcp_servers=[server]). The agent receives Heap tools as native definitions — JSON schemas resolve automatically.
4

Run the agent

Call Runner.run(agent, prompt) to execute. The agent invokes the appropriate Heap tools and returns structured results. Copy the full example on the right to get started.

agent.py

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    async with MCPServerSse(
        url="https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    ) as server:
        agent = Agent(
            name="Heap Agent",
            instructions="You have access to Heap tools.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "List recent transactions")
        print(result.final_output)

asyncio.run(main())

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 OpenAI Agents SDK

You just need the Vinkius endpoint URL. Instantiate `MCPServerStreamableHttp` with the URL and pass it to your Agent constructor. The tools are discovered automatically.

Yes. The agent can use the `bulk_track_events` and `bulk_add_user_properties` tools. This is the best approach for high-throughput applications to avoid API rate limits.

Each agent in your system can use the Heap tools. Because the SDK provides tracing, you'll see a clear log of which agent initiated a `track_event` or `identify_user` call, making debugging simple.

Absolutely. The `query_user_profiles` tool lets your agent find users based on specific properties. The agent can then use that information to make decisions or update other systems.

Your agent will only access the Heap data it's instructed to, like user profiles and event properties. Vinkius secures the connection by running every API call in an isolated, ephemeral sandbox. Your single auth token is all that's needed to manage access.

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