How do I handle Heap's API rate limits when using Claude?

Truto normalizes upstream rate limit info into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) but passes HTTP 429 errors directly to the caller. Claude or your agent framework is responsible for reading the ratelimit-reset header and applying retry logic or backoff.

Can Claude execute asynchronous user deletions in Heap?

Yes. The agent first calls the create_a_heap_user_deletion tool to submit a batch of users, which returns a deletion_request_id. The agent then calls get_single_heap_user_deletion_by_id in a polling loop to verify the deletion status.

Does Truto store my Heap analytics telemetry?

No. Truto operates as a pass-through proxy. Tool execution delegates directly to the API handlers, meaning MCP tools operate on the integration's native resources directly without intermediate storage.

How does the MCP server handle authentication?

Each server URL contains a cryptographically hashed token scoped to a specific tenant connection. For zero-trust environments, you can enable require_api_token_auth, which forces the client to also provide a valid Truto API token in the Authorization header.

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. 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. If your team uses ChatGPT, check out our guide on /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/.

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.

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, 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:

Navigate to the Integrated Accounts page in your Truto dashboard and select your active Heap connection.
Click the MCP Servers tab.
Click Create MCP Server.
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.
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:

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:

In Claude, navigate to Settings -> Integrations -> Add MCP Server.
Paste the Truto MCP URL into the configuration field.
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:

{
  "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.

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:

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

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."

Handling data deletion requests manually across analytics systems is tedious and prone to error. An AI agent 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."