# Heap MCP

> Heap MCP lets your agent manage product analytics directly. Track specific user events, update profile details for groups of users, and query behavior metrics without logging into an analytics dashboard. It’s designed to let you handle everything from setting up custom event tracking on the backend to permanently deleting user data in compliance with GDPR.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** product-analytics, event-tracking, user-behavior, digital-insights, session-analysis, data-segmentation

## Description

Connecting your Heap.io account gives your AI client full control over your product data and how users behave within your application. Instead of opening complex analytics dashboards, you can talk to your agent and ask it to perform actions directly against your user base. You can send custom server-side events right from the chat window, or group multiple users together for updates using bulk operations.

Need to know what segments of your audience are doing? Your agent lists all defined segments instantly. Or maybe you just need to figure out if a specific event definition exists in your schema. You can query user profiles based on unique behaviors and attributes, making it feel like having a dedicated data analyst sitting right next to you. This capability is hosted on the Vinkius Marketplace, so once you connect your preferred client, you get access to this powerful toolset alongside hundreds of others.

It also handles compliance issues; when GDPR hits, your agent permanently deletes user records for you. It's all about taking complex data tasks and handling them through plain conversation.

## Tools

### add_account_properties
Adds or modifies properties that apply to a group of users (an account).

### add_user_properties
Sets or changes custom attributes on an individual user's profile.

### bulk_add_user_properties
Updates the properties for several users at once in a single request.

### bulk_track_events
Sends multiple user events simultaneously to record high-volume activity efficiently.

### delete_user_data
Permanently removes a specific user and all their associated data records (for GDPR compliance).

### get_api_usage
Checks your current API usage limits and overall project status.

### get_my_profile
Retrieves basic information about the credentials used to connect this MCP.

### identify_user
Links an anonymous visitor's session ID to a known, persistent user identity.

### get_event_definitions
Lists all custom event names and definitions currently configured in Heap.

### get_segments
Retrieves a list of every defined user segment or cohort for your project.

### query_user_profiles
Filters and searches user profiles based on specific criteria, like actions taken or attributes set.

### track_event
Sends a single server-side event for a specified user within your product.

## Prompt Examples

**Prompt:** 
```
Track event 'Checkout Started' for user 'user_992' with properties {'value': 49.99}.
```

**Response:** 
```
Event tracked! I've successfully sent the 'Checkout Started' event for user_992 to Heap. Would you like to check the current properties for this user profile?
```

**Prompt:** 
```
List all active segments in the project.
```

**Response:** 
```
I've retrieved your segments. You have 5 active cohorts, including 'Power Users', 'Churn Risks', 'Trial Users', and 'New Signups'. Which segment would you like to query for user details?
```

**Prompt:** 
```
Identify user 'anon_552' as 'john.doe@example.com'.
```

**Response:** 
```
User identified! I've linked the anonymous session 'anon_552' to the identity 'john.doe@example.com' in Heap. Future events from this user will now be consolidated. Should I set any initial profile properties?
```

## Capabilities

### Update User Details
Add or modify custom properties for specific users or entire groups of accounts.

### Track Events in Bulk
Send multiple user events simultaneously to record high-throughput activity across your product.

### Manage User Data Deletion
Permanently remove a user and all associated data records for compliance purposes.

### Identify Anonymous Sessions
Link an anonymous visitor session to a known, specific user identity.

### List User Cohorts
Retrieve a list of every defined segment (user group) within your project.

### Filter User Profiles
Search and retrieve user profiles based on specific actions or attributes you define.

## Use Cases

### Tracking a new feature launch
A growth engineer needs to log that users are starting to use the 'Pro Dashboard' on their account. Instead of writing code, they ask their agent to run bulk_track_events for every user who hits the dashboard, tracking the event and associated value.

### Fixing a leaky funnel segment
A product manager notices that 'Trial Users' are dropping off. They use get_segments to confirm the cohort exists, then run query_user_profiles to find exactly which users in that group viewed the pricing page but never signed up.

### Handling GDPR data removal
A data privacy officer receives a deletion request for 'jane.doe@example.com'. They prompt their agent, and it executes delete_user_data, ensuring all associated behavioral and profile records are purged instantly.

### Reconnecting anonymous sessions
A user lands on the site anonymously (anon_123). When they log in via their AI client, your agent runs identify_user to link anon_123's actions to their known account ID. All future events are consolidated.

## Benefits

- You can track multiple events concurrently using bulk_track_events, which handles high-volume data logging much faster than sending them one by one.
- Stop manually updating user records. You use add_user_properties or bulk_add_user_properties to modify attributes for entire groups of users instantly.
- Compliance is simple. When a deletion request comes in, you run delete_user_data through your agent and it handles the permanent removal.
- You don't need to guess if an event name is correct; running get_event_definitions confirms your analytics schema immediately.
- Need to know who did what? You can query user profiles using query_user_profiles, filtering by complex behaviors or attributes you care about.

## How It Works

The bottom line is that you manage complex analytics tasks by talking to your AI client instead of clicking through dashboards.

1. Subscribe to this MCP, then input your Heap App ID and API Key into the connection settings.
2. Your AI client authenticates with Heap, making all the product data available for conversation-based commands.
3. You ask your agent a question like, 'Track event X for user Y,' and it executes the command immediately.

## Frequently Asked Questions

**How do I find my Heap App ID and API Key?**
Log in to Heap, go to **Account > Projects**, and select your project. Your **App ID** will be visible there. For the **API Key**, navigate to the API section in your project settings to generate a server-side key.

**Can I track events server-side through this integration?**
Yes! Use the `track_event` tool. You provide the user identity, event name, and optional properties. This is perfect for capturing actions that happen outside the client browser.

**How do I update user properties in bulk?**
Use the `bulk_add_user_properties` tool. You must provide a JSON array containing objects with `identity` and `properties` for each user you wish to update.

**Is the data deletion tool permanent?**
Yes. The `delete_user_data` tool triggers a permanent deletion of the user identity and all historical data from Heap, helping you comply with GDPR and CCPA requests.