---
title: "Connect Heap to Claude: Enrich User Profiles and Govern Data"
slug: connect-heap-to-claude-enrich-user-profiles-and-govern-data
date: 2026-10-01
author: Riya Sethi
categories: ["AI & Agents"]
excerpt: "Learn how to build a secure MCP server for Heap to give Claude read and write access to product analytics, user identities, and account telemetry."
tldr: "Connect Heap to Claude using a managed MCP server to automate identity mapping, track server-side events, and execute GDPR deletions via natural language workflows."
canonical: https://truto.one/blog/connect-heap-to-claude-enrich-user-profiles-and-govern-data/
---

# Connect Heap to Claude: Enrich User Profiles and Govern Data


If you need to connect Heap to Claude to enrich user profiles, map cross-device identities, track server-side conversions, or automate GDPR compliance deletions, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's LLM function calls and Heap's REST APIs. You can either construct and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a [secure, authenticated MCP server URL](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/). If your team uses ChatGPT, check out our guide on [/connect-heap-to-chatgpt-track-events-and-map-user-identities/](https://truto.one/connect-heap-to-chatgpt-track-events-and-map-user-identities/) or explore our broader architectural overview on [/connect-heap-to-ai-agents-automate-account-and-event-ingestion/](https://truto.one/connect-heap-to-ai-agents-automate-account-and-event-ingestion/).

Giving a Large Language Model (LLM) read and write access to a sprawling analytics engine like Heap is an engineering challenge. You have to handle credential lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Heap's strict API quotas and asynchronous jobs. Every time Heap updates an endpoint or changes a payload requirement, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Heap, connect it natively to Claude Desktop, and execute complex analytics and data governance workflows using natural language.

> Want to give your AI agents secure, authenticated access to Heap and 100+ other SaaS APIs? Let's talk about [managed MCP architecture](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/).
>
> [Talk to us](https://truto.one/book-a-demo/)

## The Engineering Reality of the Heap API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools via JSON-RPC, the reality of implementing it against specialized B2B APIs is painful. Heap is built to ingest massive amounts of telemetry, unify user journeys, and enforce strict data retention rules. Its API reflects that complexity.

If you decide to [build a custom Heap MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), here are the specific integration challenges you will face:

**Identity Mapping Constraints**
Heap enforces strict boundaries on how you can stitch user sessions together. When mapping an anonymous SDK `user_id` to a known `identity` (like an email address), the API allows only one identity per `user_id` and at most 10 `user_ids` per identity within a one-month window. Any extra calls beyond this quota are silently ignored or rejected. An LLM has no inherent context on these limits. A managed MCP server exposes tools with explicitly documented constraints embedded in the schema, guiding the LLM to avoid blowing through identity quotas with naive retry loops.

**Asynchronous User Deletions (GDPR/CCPA)**
Deleting a user from an analytics database is not a synchronous CRUD operation. In Heap, you submit a batch of up to 10,000 users for deletion, and the API returns a `deletion_request_id` rather than a success confirmation. To verify the deletion, you must poll a secondary endpoint using that ID. LLMs struggle with asynchronous architecture unless the tools are designed to surface this workflow clearly. You must provide distinct submission and polling tools, coupled with descriptions that instruct the LLM on exactly how to chain them together.

**Rate Limits and 429 Errors**
Heap's ingestion APIs can quickly hit rate limits under heavy load. Truto does not retry, throttle, or apply backoff on rate limit errors internally. When the upstream API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller - whether that is a custom script or the Claude Desktop client - is entirely responsible for reading these headers and executing retry or backoff logic.

## How to Generate a Managed MCP Server for Heap

Truto's MCP infrastructure derives tool definitions dynamically from the integration's resource definitions and documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring that only curated, well-described endpoints are exposed to the LLM. 

Each MCP server is scoped to a single integrated account (a connected instance of Heap for a specific tenant) and requires no hand-coded schema mapping. You can generate the server using the Truto UI or programmatically via the API.

### Method 1: Generating the Server via the Truto UI

For ad-hoc agent workflows or internal operations, the UI is the fastest path:

1. Navigate to the **Integrated Accounts** page in your Truto dashboard and select your active Heap connection.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Select the desired configuration. You can apply method filters (e.g., restricting the server to only `read` or `write` operations) and set an expiration time.
5. Copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4e5f6...`).

### Method 2: Generating the Server via the API

For production workflows, you can dynamically provision MCP servers on behalf of your users via the Truto API. The API validates that the integration has tools available, generates a secure token, stores it in distributed key-value storage, and returns a ready-to-use URL.

Make an authenticated POST request to `/integrated-account/:id/mcp`:

```typescript
const response = await fetch(
  'https://api.truto.one/integrated-account/YOUR_HEAP_ACCOUNT_ID/mcp',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TRUTO_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Claude Analytics Agent",
      config: {
        methods: ["write", "custom"], // Filter out read-only ops if desired
        require_api_token_auth: false
      },
      expires_at: "2026-12-31T23:59:59Z" // Optional TTL
    })
  }
);

const mcpServer = await response.json();
console.log(mcpServer.url); // Pass this URL to Claude
```

## Connecting the Heap MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero custom code. The server URL contains a cryptographic token that encodes the account routing and tool configuration.

### Method A: Via the Claude UI

If you are using the Claude web interface or enterprise workspace:

1. In Claude, navigate to **Settings -> Integrations -> Add MCP Server**.
2. Paste the Truto MCP URL into the configuration field.
3. Click **Add**.

Claude will immediately execute the JSON-RPC `initialize` handshake and call `tools/list` to discover the available Heap operations.

### Method B: Via the Claude Desktop Config File

For local development or custom agent deployments, you can configure Claude Desktop to use Truto's server via the Server-Sent Events (SSE) transport adapter.

Open your `claude_desktop_config.json` file (typically located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add the following configuration:

```json
{
  "mcpServers": {
    "heap_analytics": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}
```

Restart Claude Desktop. The agent will parse the flat input namespace of the Heap schemas and present the tools natively in the chat interface.

## Security and Access Control

Handing an LLM direct access to product telemetry and user deletion APIs requires strict guardrails. Truto's MCP implementation provides four layers of security configuration at the token level:

*   **Method Filtering:** Enforce least-privilege by restricting the server to specific HTTP verbs. Pass `config.methods: ["read"]` to block the LLM from executing `create`, `update`, or `delete` tools. 
*   **Tag Filtering:** Group tools by functional area. If Heap resources are tagged in Truto (e.g., `["governance"]`), you can restrict the MCP server to only expose tools with that specific tag.
*   **Expiration (TTL):** Set an `expires_at` timestamp for temporary access. Truto automatically schedules a distributed cleanup alarm that invalidates the token and purges the key-value storage exactly when the timer expires.
*   **Additional Authentication:** Enable `require_api_token_auth: true` to prevent anonymous access via the URL. When enabled, the MCP client must send a valid Truto API token in the `Authorization` header, tying tool execution to an authenticated session.

## Heap Hero Tools for Claude

Truto automatically translates Heap's complex JSON schemas into descriptive, snake_case MCP tools. Query parameters and body parameters share a flat input namespace, which Truto safely splits before delegating execution to the proxy handlers.

Here are the highest-leverage tools available for Heap.

### 1. `create_a_heap_event`

Send a custom server-side event to Heap. This is critical for tracking backend transactions, subscription upgrades, or data not capturable client-side. The tool requires `app_id` and the `event` payload. You must supply exactly one of `identity` or `user_id`.

> "Claude, a user just completed a manual wire transfer for invoice #994. Please send a server-side event to Heap for app ID '12345'. The identity is 'corp-finance@example.com'. The event name is 'Wire Transfer Processed' and include the invoice number in the properties."

### 2. `update_a_heap_identity_by_id`

Map an anonymous SDK `user_id` to a known `identity` (like an email address). This migrates all historical anonymous events to the unified user profile. Note the strict quota: Heap allows only 1 identity per `user_id` and at most 10 `user_ids` per identity in a month.

> "Claude, we just had a successful login for session ID 'anon-8472'. Call the Heap API to map this user_id to the identity 'j.doe@example.com' for app ID '12345'."

### 3. `update_a_heap_user_by_id`

Attach custom key-value properties to an identified user. If the identity is unknown, Heap creates a new user profile. Existing properties with the same names are overwritten.

> "Claude, update the Heap profile for identity 's.connor@example.com'. Add a custom property called 'Account Tier' set to 'Enterprise' and 'LTV' set to '15000'."

### 4. `update_a_heap_account_by_id`

Attach or update custom account-level properties for B2B analytics. You can update a single account by providing `account_id` and `properties`, or execute a bulk update via the `accounts` array.

> "Claude, the customer success team just marked account 'Acme Corp' as a churn risk. Update this account in Heap to set the 'Health Score' property to 'Red' and 'Renewal Date' to '2026-10-01'."

### 5. `create_a_heap_user_deletion`

Submit a batch of up to 10,000 users for deletion from Heap to comply with GDPR or CCPA. This is an asynchronous operation. The tool requires an array of `users` (each with `user_id` or `identity`) and returns a `deletion_request_id`.

> "Claude, we received a GDPR right-to-be-forgotten request for the identity 'data-privacy@example.com'. Submit a deletion request to Heap and give me the deletion request ID."

### 6. `get_single_heap_user_deletion_by_id`

Check the status of a previously submitted user deletion request. The LLM must pass the `id` returned from the creation tool.

> "Claude, check the status of Heap deletion request ID 'del-99382'. Let me know if the status is pending or completed."

For the complete inventory of available Heap tools and their underlying JSON schemas, view the [Heap integration page](https://truto.one/integrations/detail/heap).

## Workflows in Action

Connecting an LLM to Heap transforms how engineering and data teams handle telemetry mapping and governance. Because the LLM understands the schema requirements, it can chain operations logically without manual scripts.

### Workflow 1: Automated B2B Account Enrichment and Identity Mapping

When a new high-value user signs up, the agent maps their anonymous session to their email, updates their company's B2B account properties, and logs the backend conversion event - all in one natural language prompt.

> "Claude, we have a new signup. Map anonymous user_id 'anon-xyz' to 'cto@cyberdyne.com'. Then, update the account 'Cyberdyne Systems' to set 'Plan' to 'Enterprise'. Finally, log a server-side event called 'Enterprise Signup Processed' for this identity."

**Execution Steps:**
1.  Claude calls `update_a_heap_identity_by_id` with `user_id: "anon-xyz"` and `identity: "cto@cyberdyne.com"`.
2.  Upon receiving a success acknowledgement, Claude calls `update_a_heap_account_by_id` with `account_id: "Cyberdyne Systems"` and the requested properties.
3.  Finally, Claude calls `create_a_heap_event` to log the "Enterprise Signup Processed" event.

```mermaid
sequenceDiagram
    participant User as Human
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Heap as Heap API

    User->>Claude: "Map anon-xyz to cto@cyberdyne.com, update account..."
    Claude->>Truto: call tool update_a_heap_identity_by_id
    Truto->>Heap: POST /api/capture/v1/identify
    Heap-->>Truto: 200 OK
    Truto-->>Claude: Result: Success
    
    Claude->>Truto: call tool update_a_heap_account_by_id
    Truto->>Heap: POST /api/capture/v1/account_properties
    Heap-->>Truto: 200 OK
    Truto-->>Claude: Result: Success
    
    Claude->>Truto: call tool create_a_heap_event
    Truto->>Heap: POST /api/capture/v1/track
    Heap-->>Truto: 200 OK
    Truto-->>Claude: Result: Success
    Claude-->>User: "Identity mapped, account updated, and event logged."
```

### Workflow 2: GDPR Compliance - Async User Deletion and Verification

Handling data deletion requests manually across analytics systems is tedious and prone to error. An [AI agent](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) can handle the asynchronous nature of the Heap API flawlessly.

> "Claude, submit a GDPR deletion request for 'j.smith@example.com'. After you submit it, check the status immediately. If it is still pending, just tell me the deletion request ID so I can track it later."

**Execution Steps:**
1.  Claude calls `create_a_heap_user_deletion`, passing `users: [{ identity: "j.smith@example.com" }]`.
2.  Heap returns a payload containing `deletion_request_id: "dr-12345"`.
3.  Claude parses the response and immediately calls `get_single_heap_user_deletion_by_id`, passing `id: "dr-12345"`.
4.  Heap responds with `status: "pending"`.
5.  Claude reports the status and the ID back to the user.

```mermaid
sequenceDiagram
    participant User as Human
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Heap as Heap API

    User->>Claude: "Submit GDPR deletion for j.smith@example.com..."
    Claude->>Truto: call tool create_a_heap_user_deletion
    Truto->>Heap: POST /api/v1/users/delete
    Heap-->>Truto: { "deletion_request_id": "dr-12345" }
    Truto-->>Claude: Result: dr-12345
    
    Claude->>Truto: call tool get_single_heap_user_deletion_by_id
    Truto->>Heap: GET /api/v1/users/delete/dr-12345
    Heap-->>Truto: { "status": "pending" }
    Truto-->>Claude: Result: pending
    Claude-->>User: "Deletion submitted. Request ID is dr-12345. Status is currently pending."
```

Integrating Heap with Claude doesn't have to mean writing custom JSON-RPC wrappers, fighting asynchronous job polling, or managing secure token lifecycles in-house. By utilizing a managed MCP architecture, you bridge the gap between natural language reasoning and strict analytics governance, allowing your engineering and data teams to interact with their telemetry stack at the speed of thought.