Heap
Connect Heap to ask about events, segments and trends in your product data, send server-side events and properties, and handle user deletion requests.
Nothing has to be typed into PopMCP to ask questions. You click Sign in with Heap, sign in and approve. There is no developer app or callback URL to set up. To send events and properties or delete users, you use an App ID and API key under More options instead, which a Heap admin finds under Account, Manage, Privacy & Security.
- Setup time
- 1 min
- Auth
- OAuth authorization
- API base URL
- https://mcp.heapanalytics.com/mcp
Before you begin
- A Heap account with access to Heap MCP. If you cannot find it, look under Integrations, then MCP, in Heap, or ask your Heap admin
- Pop-up blockers must allow the Heap sign-in window to open
- Only to send data or delete users: a Heap admin, who can make the API key, and an owner or admin in PopMCP to allow write actions
Get your credentials
Start the connection from PopMCP
Open the Heap connector in PopMCP and click Sign in with Heap. There are no fields to fill in. If you sign in to Heap at eu.heapanalytics.com, open More options first and type EU under Data region.
Sign in to Heap and approve
If you are not signed in to Heap in this browser, Heap shows its normal login page first. Then approve the access PopMCP asks for. One sign-in reaches the Heap projects your own account can see.
Back in PopMCP
You return to PopMCP, connected, with the tools Heap offers your account. If you have several Heap environments, your AI asks which one to use, and Heap remembers the choice. This connection only reads aggregated numbers.
Or connect with an App ID and API key
Optional, instead of signing in, to send events and properties or delete users. A Heap admin opens Account, Manage, Privacy & Security. The App ID is on this page. Under Delete End User Data, choose to use the API and generate a key if there is none yet. Copy both, open More options in PopMCP and paste them. Use the App ID of your Main Production environment, because the key works with no other. This connection cannot read Heap: to have both, add a second connection.
Privacy & Security
Send to a development environment
Optional, to test what you send before it reaches production. Find the ID of a development environment under Account, Manage, Projects in Heap, and put it in Send events to another environment. The App ID and API key stay the ones from Main Production. Heap cannot confirm the ID is yours, so check it first.
Connect in PopMCP
Open your workspace, choose Heap in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| How you connectpreset | Click Sign in with Heap, sign in and approve. There is nothing to copy or paste. If you sign in to Heap at eu.heapanalytics.com, open More options and type EU first. |
| Data regiontext | Leave this blank for the US. Type EU if you sign in to Heap at eu.heapanalytics.com. |
| App ID (to send data, instead of signing in)text | Signing in reads your data. To send events and properties or delete users, paste your App ID and API key here instead. In Heap, open Account, Manage, Privacy & Security. Use the App ID of Main Production. |
| API key (with the App ID)secret | On the same page, under the option to use the API. An admin can make one. Stored encrypted and used only on our servers.Encrypted with AES-256-GCM on save and never shown again. |
| Send events to another environmenttext | To test on a development environment first. Find its ID under Account, Manage, Projects in Heap. |
PopMCP verifies the credential against Heap immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Permissions PopMCP requests
These are the scopes sent to Heap at authorization time.
| Scope | Why PopMCP asks for it |
|---|---|
| heap.mcp | The only permission Heap's sign-in has. It reads aggregated numbers and metadata from the projects your account can see, and cannot create, change or delete anything. |
Verify it worked
The Heap card in PopMCP shows Connected. A signed-in connection shows how many tools Heap offers, and asking the AI for the connection profile (heap_connection_profile) lists them. A connection made with an App ID and API key is checked by asking Heap for a token, and the profile says where events are sent.
Troubleshooting
The sign-in window never opens
Why: A pop-up blocker is stopping the Heap sign-in window.
Fix: Allow pop-ups for PopMCP in your browser and click Sign in with Heap again.
Heap will not sign you in, or says it does not know your account
Why: Your Heap data is in the EU data center, and the connection went to the US.
Fix: Open More options, type EU under Data region and sign in again. You are on the EU data center if you normally sign in at eu.heapanalytics.com.
Heap signed me in, but PopMCP says it offered no tools
Why: Your Heap account does not have access to Heap MCP yet.
Fix: Look under Integrations, then MCP, in Heap, or ask your Heap admin to turn it on. Then connect again.
Heap did not accept this App ID and API key
Why: The App ID is not the one for Main Production, the key was replaced, or part of it was not copied.
Fix: Copy both again from Account, Manage, Privacy & Security in Heap. The App ID on that page is the right one. Only an admin can see the key.
The AI says it cannot read events or reports
Why: This connection was made with an App ID and API key, which only send data.
Fix: Add a second Heap connection by clicking Sign in with Heap. To ask questions you need the signed-in one.
The AI says it cannot send an event
Why: This connection was made by signing in, which only reads, or it is a key connection still set to read-only.
Fix: Add a connection with an App ID and API key, and have an owner or admin in PopMCP allow write actions on it.
Events I sent do not appear in Heap
Why: They may still be processing, they went to another data region or environment, or the identity is spelled differently. Identities are case-sensitive.
Fix: Wait a little and check again. Ask the AI for the connection profile to see the data region and where events are sent, and reconnect with the right region if it is wrong.
Heap will not take a new identity for a user
Why: Heap maps a user_id to one identity only, and drops later attempts without an error. An identity also takes at most 10 user_ids a month.
Fix: Check the spelling before you identify someone. A mapping cannot be changed through the API.