Heap MCP Server

Heap is a digital analytics platform that automatically captures user interactions and provides APIs to enrich that data with custom events, user properties, and account-level information.

Tools

Last Updated

Apr 7, 2026

What is the Heap MCP Server?

The Heap MCP server gives AI agents structured, permission-aware access to Heap through the Model Context Protocol. With 12 pre-built actions, agents can read, create, and update Heap data on behalf of authorized users.

Willow ships the Heap MCP server as part of an enterprise control plane. Every call runs behind SSO (Okta, Azure AD), enforces RBAC and least-privilege at runtime, writes to a full audit trail, and integrates with Splunk and Loki for SIEM visibility. Connect from Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, n8n, or any custom agent. Install once, distribute org-wide, and see exactly how Heap is being used by every AI agent in your stack.

Tools

Track Custom Event

Send custom events to Heap that aren't automatically captured, such as purchase information, backend events, email sends, or completed transactions. Use this when you need to track server-side events or events that happen outside of the user's browser. Either identity or user_id is required, but not both. Event names are limited to 255 characters.

Track Event with User Properties

Send a custom event and update user properties in a single API call. This is useful for tracking events like user signup where you want to both record the event and attach user metadata (name, email, account tier, etc.) at the same time. Either identity or user_id is required, but not both.

Batch Track Events

Track multiple custom events efficiently in a batch. This is useful when you need to send many events at once, such as importing historical data, processing batch jobs, or syncing offline events. Note: This creates multiple API calls internally, one per event.

Identify User

Link an anonymous user_id from the Heap SDK to a known identity (such as email address or user ID). When this is called, all events associated with the provided user_id are migrated to the user with the provided identity. This enables you to track users across sessions, devices, and browsers. IMPORTANT: Only 1 identity can be mapped to a user_id. Maximum of 10 different user_ids can be mapped to one identity within a one-month period. Subsequent calls that exceed these limits are ignored.

Add User Properties

Attach custom properties to identified users from your server, such as Sign Up Date (in ISO8601 format), Total Transactions Completed, Total Dollars Spent, Subscription Tier, Account Type, etc. These properties are associated with all of the user's past activity and future activity. Properties are stateless - only the most recent value is stored. Heap will create a new property if it doesn't exist, or overwrite the previous value if one exists with the same name. IMPORTANT: To write to the built-in Email property, use lowercase 'email' as the key. Rate limit: 30 requests per 30 seconds per identity per app_id.

Add Account Properties (Single)

Attach custom properties to a single account for B2B analytics and account health analysis. Use this to send account-level properties like payment tier, account owner, account name, company size, subscription status, renewal date, etc. You must configure the Account ID setting in Heap before using this API. As your accounts and properties change, periodically call this API with the account ID and updated properties. This is useful for measuring account health and analyzing B2B customer behavior.

Add Account Properties (Bulk)

Attach custom properties to multiple accounts at once for efficient B2B data enrichment. Use this when you need to update many accounts, such as importing account data from your CRM, syncing subscription changes, or updating account health scores across your customer base. Maximum of 1000 accounts per request. Each account object must have an account_id and properties object.

Link User to Account

Associate a user with an account for B2B account-level analytics. This enables you to analyze behavior at the account level (e.g., which accounts are most engaged, which accounts are at risk of churn). The account_id must match an account that has been configured in Heap. Use this after identifying a user to establish the user-to-account relationship.

Get Auth Token

Obtain a temporary authentication token for the User Deletion API. This token is required before calling Delete Users or Check Deletion Status. The token expires in 5 minutes. Uses HTTP Basic Authentication with your app_id and api_key. IMPORTANT: The app_id must be from your Main Production environment - other environment IDs will result in an Unauthorized response. The deletion API checks all environments in your account.

Delete Users

Submit users for deletion from your Heap account to comply with GDPR and data privacy regulations. This API checks all environments in your account and deletes user records and data across all of them. You can submit up to 10,000 users in a single request using either user_id or identity. Returns a deletion_request_id that you can use to check the deletion status. IMPORTANT: You must first call Get Auth Token and use the returned access_token as a bearer token for this request. The deletion process may take time to complete - use Check Deletion Status to monitor progress.

1 2

1–10 of 12 tools

Customize Tools

Edit descriptions, modify arguments, select tools, or add new ones

Set Up Your Heap MCP Server in Minutes

Add the following configuration to your MCP client. Authentication is handled via OAuth. Compatible with Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, n8n, and any MCP-compatible agent.

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "willow-heap": {
      "type": "http",
      "url": "https://<org>.mcp-s.com/mcp/mcp/heap"
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "willow-heap": {
      "type": "http",
      "url": "https://<org>.mcp-s.com/mcp/mcp/heap"
    }
  }
}

Claude Code

CLI

claude mcp add willow-heap --transport http https://<org>.mcp-s.com/mcp/mcp/heap

n8n

HTTP Request Node

{
  "url": "https://<org>.mcp-s.com/mcp/mcp/heap",
  "method": "POST"
}

Or click "Install with Willow" above to set up automatically with SSO and RBAC preconfigured.

Enterprise Governance for Heap

Willow adds the layer Heap and every other SaaS doesn't ship out of the box: every call runs behind SSO (Okta, Azure AD), enforces RBAC and least-privilege at runtime, writes to full audit logs, and detects shadow AI usage across your stack. One MCP gateway. Any agent. Every tool.

Heap MCP Server FAQ

What is the Heap MCP server?

The Heap MCP server is a Model Context Protocol implementation that lets AI agents like Claude, Cursor, and ChatGPT read and write Heap data through a standardized interface. Willow hosts and governs this server so enterprises can roll it out without a security review backlog.

How is Willow's Heap MCP server different from the official one?

The official Heap MCP server is scoped to a single user's account and does not include enterprise governance. Willow's version adds SSO, RBAC, audit logging, shadow AI detection, and centralized control over which actions agents can take across the entire org.

Which AI clients work with the Heap MCP server?

Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code with MCP support, n8n, and any custom agent built with OpenAI Agents SDK, LangChain, Vercel AI SDK, or Anthropic SDK.

Is the Heap MCP server secure? How does Willow handle authentication?

Every call runs behind your existing SSO (Okta, Azure AD). Per-user OAuth scopes the agent to exactly what that user can do in Heap, nothing more. No credentials reach the LLM. Every action writes to an audit trail.

Can I limit which Heap actions agents can take?

Yes. Willow lets you scope agents to specific actions, specific projects, or specific environments. Toggle actions on or off in the dashboard, or enforce policy via infrastructure-as-code through GitHub.

How do I detect shadow Heap MCP servers in my org?

Willow's browser extension and discovery service surface unmanaged MCP servers, skills, and AI agents across the org. If a developer installed an unapproved Heap MCP locally, you'll see it.

What does the Heap MCP server cost?

Pricing depends on org size and deployment model (SaaS, dedicated cloud, self-host). See withwillow.ai/pricing or contact sales for a quote.

How do I install the Heap MCP server with Willow?

Install via the Willow Connect Panel in one click, or paste the JSON snippet above into your Claude Desktop, Cursor, or Claude Code config. SSO and RBAC inherit from your existing Willow setup.