Heap MCP lets you connect an AI client to a Heap project and ask questions about your Heap data using natural language. Your AI agent can search your Heap definitions, select a supported analysis, run it, and explain the results.
Heap MCP is read-only. It can analyze your Heap data but cannot create or modify events, properties, segments, charts, or dashboards.
When to use Heap MCP
Heap offers several ways to work with analytics and AI. Choose the option that matches your workflow.
| Solution | Best for | How it works |
| Heap | Deep analysis, report building, and data governance | Build and explore analyses directly in Heap. |
| Sense Chat | Quick AI-powered insights without leaving Heap | Ask a question in Heap and receive an AI-generated answer or chart. |
| Heap MCP | AI-driven workflows in external AI tools | Ask questions about Heap data from an MCP-compatible AI agent outside Heap. |
| Heap Connect | Custom data models and advanced data engineering | Export Heap’s behavioral data to a data warehouse for custom queries, models, and dashboards. |
Heap MCP is the right choice when you want to access Heap analytics from the AI tool your team already uses, without opening the Heap interface. It is intended for conversational, on-demand analysis and does not replace the Heap interface for detailed investigation or Heap Connect for warehouse-based analysis.
Heap MCP and data warehouses
Heap MCP and a data warehouse serve different purposes:
| Use Heap MCP when you want to… | Use a data warehouse when you want to… |
|---|---|
| Ask questions about current Heap project data in natural language. | Query long-term historical data stored outside Heap. |
| Avoid exposing warehouse schemas and join logic to the AI agent. | Use existing warehouse models, transformations, and governance. |
| Work with the data available in your Heap project. | Work with data that has been exported, transformed, or combined outside Heap. |
Heap MCP does not replace an existing data warehouse workflow. You can use each approach for the type of analysis it supports best.
Before you begin
Make sure you have:
- Admin access in Heap, as well as Admin access to the AI client.
- A Heap account with Heap MCP enabled.
- An AI agent that supports remote MCP connections and OAuth authentication.
Prepare your Heap data
Heap MCP searches the events, properties, and segments that already exist in your connected project. It does not decide which definition is correct when multiple definitions have similar names.
Before using Heap MCP for important analyses:
- Review duplicate or competing definitions.
- Standardize event, property, and segment names where possible.
- Hide or deprecate definitions that should not be used.
- Confirm which definitions represent important business actions, such as sign-up, purchase, or checkout completion.
You can also ask the AI agent to show the definitions it selected before running an analysis:
- Which events and properties did you select for this analysis?
- Find the events that represent the start and completion of checkout. Do not run the analysis yet.
This helps you verify that the analysis uses the intended Heap definitions.
How to connect an AI agent to Heap MCP
In Heap, go to Integrations > MCP. Scroll down to Set up the Heap MCP Server and follow the instructions for the AI client you want to connect.
How to use Heap MCP
After connecting Heap MCP, ask questions about your data in natural language. Include the following information when relevant:
- The event, property, or segment you want to analyze.
- The analysis type, such as a funnel or count.
- The date range.
- Any comparison period.
- The environment.
- The breakdown or filter you want to use.
For example:
- What was the checkout conversion rate over the last 30 days compared with the previous period?
- How many users completed the sign-up event over the last 7 days?
- Which campaign property was associated with the most sign-ups yesterday?
- Compare the checkout funnel for new users and returning users over the last 30 days.
- What properties are available for the sign-up event?
Ask one question at a time
For more reliable results, start with one analysis question. You can then ask follow-up questions to refine the result.
For example:
- What was the checkout conversion rate over the last 30 days?
- Compare that with the previous 30-day period.
- Break the results down by device type.
Confirm the project and environment
If the results do not look correct, confirm that the AI agent is using the intended project and environment.
Ask:
Which Heap project and environment did you use for this answer?
You can then switch environments if needed:
Use the Staging environment and rerun the analysis.
Heap MCP queries current Heap project data, subject to Heap’s normal processing delay. Data may have an approximate 30–60 minute delay.
Supported analyses
- Count and aggregation
- Funnel analysis
- Event, property, and segment metadata search
Heap MCP currently supports these preset date ranges:
- Today
- Yesterday
- Last 7 days
- Last 30 days
- Last 90 days
- Year
Comparison periods, such as comparing the current period with the previous period, are supported. Custom absolute date ranges and all-time date ranges are not currently supported.
Data, privacy, and security
Heap MCP follows these principles:
- Read-only access: The AI agent cannot create, update, or delete Heap data.
- Existing permissions apply: The AI agent can access only the data available to the authorized Heap user.
- Data retention applies: Heap MCP cannot return data outside your Heap retention window.
- Aggregated data and metadata: MCP responses do not include user names, email addresses, or other personal identifiers.
- Session replay is not included: Heap MCP does not return session replay data.
- Data is not used to train third-party AI models: Data accessed through Heap MCP is not used to train third-party models.
- Regional processing: EU projects use the appropriate EU infrastructure.
- Data freshness: Heap data may have an approximate 30–60 minute delay, consistent with the Heap application.
You are responsible for securing the AI agent and account you use to connect to the Heap MCP. Review the security and privacy settings of your AI provider before connecting it to Heap.
What Heap MCP does not support
Heap MCP does not currently support:
- Creating or modifying Heap events, properties, segments, or other definitions.
- Session replay data.
- Saved charts or dashboards.
- Running saved charts.
- Querying multiple Heap projects through one connection.
- Scheduled background monitoring.
- Automatic anomaly detection.
- Triggering actions in other systems through Heap MCP.
- Custom absolute date ranges.
- All-time date ranges.
Disconnecting an AI agent
To disconnect Heap MCP, remove the Heap MCP server or connector from the AI client.
The exact steps depend on the AI client, but you can usually find the connection in its MCP, Connectors, or Integrations settings and delete or remove the Heap MCP entry.
Heap does not provide a self-serve option to disconnect an AI client from the Heap interface. Heap is used to authenticate you and approve the connection; connection management happens in the AI client.
FAQs
Can I connect more than one Heap environment?
During setup you will choose one environment to start with, but can ask the agent to switch to other environments.
How does Heap MCP choose an event or property?
Heap MCP searches the definitions available in the selected environment. If multiple definitions have similar names, the AI agent may need additional instructions to select the correct one.
Ask the AI agent to show the definitions it selected before running an important analysis.
Why can’t my AI agent connect to Heap MCP?
Check the following:
- The Heap MCP URL is correct.
- Your AI agent supports remote MCP connections and OAuth.
- You are signed in to the correct Heap account.
- You have access to the Heap project.
- Your project is enabled for Heap MCP.
If the problem continues, remove the connection and add it again.
Why did the AI agent use the wrong environment?
Heap MCP uses the project’s default environment unless you select another environment. Ask the AI agent to list the available environments and specify the environment you want to use before rerunning the analysis.
Why are the results different from what I see in Heap?
Check that:
- The AI agent is connected to the correct project.
- The correct environment is selected.
- The date range matches the date range in Heap.
- The event, property, or segment definition is correct.
- The data has finished processing. Heap data may have a 30–60 minute delay.
Can Heap MCP modify my Heap data?
No. Heap MCP is read-only. It can search definitions and run analyses, but it cannot create, update, or delete Heap data.
Can Heap MCP return session replay data?
No. Session replay data is not included in the current Heap MCP scope.
Does Heap MCP include personal information?
Heap MCP responses contain aggregated analytics data and metadata. They do not include user names, email addresses, or other personal identifiers.
Can Heap MCP replace my Heap dashboards or data warehouse?
No. Heap MCP is intended for conversational, on-demand analysis. The Heap interface remains appropriate for detailed investigative analysis, while dashboards and data warehouses remain appropriate for standardized reporting, historical analysis, and cross-system analysis.
How do I refresh an expired connection?
Heap MCP uses short-lived access tokens and refresh tokens. Most compatible AI agents renew the connection automatically. If your agent cannot renew the connection, remove the Heap MCP connection and add it again.
How is Heap MCP different from Contentsquare MCP?
Heap MCP and the existing Contentsquare MCP server are separate integrations. They provide access to different data and use different project, environment, permission, and analysis models.