# Heap MCP > Heap MCP Server. Track, manage, and query all user behavior and product events directly from your AI client. Use this server to send custom server-side events, update user profiles, segment cohorts, and comply with GDPR data deletion requests, all through conversation. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** product-analytics, event-tracking, user-behavior, digital-insights, session-analysis, data-segmentation ## Description You can hook up your **Heap.io** analytics account to your AI client and manage all your product data and user identities just by talking to your agent. You don't gotta mess around in complex dashboards to track an event or check a segment size; your agent handles it. **Track User Actions:** You can send specific, custom server-side events to Heap, capturing the exact moment a user does something. To log a single event for a specific user, use `track_event`. If you're logging a bunch of events at once, use `bulk_track_events`. You also gotta know what custom event definitions you've set up; use `get_event_definitions` to list 'em. **Define or Update User Profiles:** You can add or update custom properties for a specific user by calling `add_user_properties`. If you wanna update a whole group of users, use `bulk_add_user_properties` to change properties for multiple profiles in one shot. You can also add or update properties for a defined group of users (an account) using `add_account_properties`. To see what data's attached to a user, you can run `query_user_profiles` to filter and get profiles based on specific attributes or behaviors. If you need to know about the API key your agent is using, check `get_my_profile`. **Connect Anonymous Sessions:** When a user is anonymous, you can link that session (like a browser ID) to a known user identity using `identify_user`, making sure all future events track to the right person. **Manage User Groups:** You can list every user segment (cohort) defined in your Heap project by calling `get_segments`. You can also check your current Heap API usage and project status with `get_api_usage`. **Comply with Data Deletion:** To handle GDPR or CCPA requests, you can permanently delete a user and all their associated data using `delete_user_data`. **Other Functions:** You can also use `get_my_profile` to get info on the API key, and `query_user_profiles` to pull user profiles based on criteria. You can check the usage status with `get_api_usage`. ## Tools ### add_account_properties Adds or updates properties for a defined group of users (an account). ### add_user_properties Adds or updates custom properties to a specific user's profile. ### bulk_add_user_properties Updates custom properties for multiple user profiles in one request. ### bulk_track_events Tracks multiple user events at once, which is fast for high-volume logging. ### delete_user_data Permanently deletes a user and all their associated data, fulfilling GDPR requirements. ### get_api_usage Checks your current Heap API usage and project status. ### get_event_definitions Lists every custom event definition set up in your Heap project. ### get_my_profile Retrieves information about the API key currently being used. ### get_segments Lists all the user segments (cohorts) defined in your Heap project. ### identify_user Links an anonymous session to a known user identity so future events track correctly. ### query_user_profiles Filters and retrieves user profiles based on specific criteria or attributes. ### track_event Tracks a single, server-side event for a specific user in Heap. ## 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 ### Track User Actions Send specific, custom server-side events to Heap, capturing the exact moment a user performs an action. ### Define or Update User Profiles Add, change, or update custom properties for a single user or a group of users. ### Connect Anonymous Sessions Link an anonymous user session (like a browser ID) to a known, specific user identity. ### Query User Behavior Filter and retrieve user profiles based on criteria like specific attributes or behaviors. ### Manage User Groups List all defined user segments (cohorts) within your Heap project. ### Comply with Data Deletion Permanently delete all data associated with a user ID, fulfilling GDPR or CCPA requests. ## Use Cases ### Debugging a Funnel Leak The QA team notices a drop-off between 'Add to Cart' and 'Payment'. They ask the agent to `query_user_profiles` for users who triggered the 'Add to Cart' event but who do not have a 'Payment Initiated' event. The agent runs the query and returns a list of IDs, allowing the team to immediately investigate the missing step. ### Handling GDPR Requests A user contacts support and requests data deletion. Instead of opening a support ticket and manually scrubbing databases, the agent runs `delete_user_data` with the user's ID. The process is logged, verifiable, and done in seconds. ### Batch Updating User Status The marketing team runs a campaign and needs to tag 5,000 users as 'High Value Lead'. They use `bulk_add_user_properties` to apply this single property update across the entire group, saving massive manual data entry. ### Analyzing Cohort Health The PM needs to see how many 'Premium' users are currently active. They ask the agent to `get_segments` first, confirming the segment exists. Then, they ask to `query_user_profiles` filtered by the 'Premium' segment to get the precise count. ## Benefits - **Bulk Operations:** Instead of sending 100 individual API calls, use `bulk_track_events` to send a hundred events in one go. This keeps your logging fast and prevents rate limiting issues. - **Identity Resolution:** Use `identify_user` to link anonymous sessions to specific user IDs. This ensures that all future events are correctly attributed to the right person, eliminating data silos. - **Compliance:** Need to delete user data for GDPR? Call `delete_user_data`. It permanently removes the user and all linked data. This is a single, verifiable chat command. - **Deep Querying:** Don't just look at basic metrics. Use `query_user_profiles` to filter users based on complex criteria, like 'all users who saw page X but never completed checkout'. - **Schema Alignment:** Use `get_event_definitions` to check your current schema. You can verify if the event name you want to track actually exists before running `track_event`. - **Account Management:** Need to update a group of users? `bulk_add_user_properties` handles updating properties for multiple accounts at once, saving time. ## How It Works The bottom line is that you use natural language to trigger complex data operations that would normally require manual API calls and dashboard navigation. 1. First, you subscribe to the Heap MCP Server and provide your Heap App ID and API Key. 2. Then, you ask your AI agent to perform an action—for instance, 'List all active segments' or 'Track event X for user Y'. 3. The agent executes the necessary tool call, interacts with the Heap API, and returns the structured data or a confirmation message to you. ## 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. **How do I use the `query_user_profiles` tool to filter user data?** You pass criteria (attributes or behavior) directly to the tool. The system returns a list of matching profiles, allowing you to analyze specific user groups instantly. **Can I use `bulk_track_events` if I'm sending data from multiple sources?** Yes, `bulk_track_events` is built for high throughput. You bundle multiple event payloads into a single request, making it efficient for multi-source data ingestion. **What is the difference between `add_user_properties` and `add_account_properties`?** The difference is scope: `add_user_properties` updates a single user profile. `add_account_properties` affects all users within a defined group or account. **Does `delete_user_data` handle data deletion for multiple users?** The tool deletes data for one user at a time. You must call `delete_user_data` sequentially for each user ID you want to remove.