How to Use the Heap MCP in Windsurf

Q: Can Cascade use Heap to debug user paths while I write code in Windsurf?

Yes, Cascade calls geteventdefinitions to inspect your active Heap actions while you write code in Windsurf. This lets Cascade suggest code changes based on actual user drop-off points in your Heap funnel. You get data-driven code suggestions without leaving your active Windsurf file.

Q: How does Windsurf handle high-volume analytics testing with Heap?

Cascade uses bulkadduserproperties to update multiple test accounts in Heap at once during your Windsurf session. This prevents your Windsurf editor from freezing up during heavy testing sessions. Cascade runs these batches in the background while you continue coding in Windsurf.

Q: What happens in Windsurf if my Heap API key expires?

The getmyprofile tool fails immediately and alerts Cascade of the authentication error in Windsurf. You will see a clear Heap connection error message in your Windsurf output panel. Simply update your Heap credentials in the Windsurf configuration file to restore the connection.

Let Cascade track user behavior and update traits in Windsurf without writing tracking code by hand.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Heap MCP to Windsurf

Create your Vinkius account to connect Heap to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Heap with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate Heap Event Tracking in Windsurf

`track_event` lets your Cascade agent record user interactions directly from your Windsurf workspace using this MCP connection. When you ask Cascade to add a new checkout button, it doesn't just write the frontend code in Windsurf; it also chains the implementation with this tool to instantly register the new event in your Heap project.

Sync Heap User Profiles with Cascade

`identify_user` links anonymous sessions to known Heap profiles while Cascade tests your authentication flows in Windsurf. Your agent uses this tool to check how identity stitching behaves before you push your authentication updates from Windsurf to production.

Query Cohorts with this Windsurf MCP Server

`get_segments` exposes your existing cohort definitions so Cascade can inspect them while writing backend logic in Windsurf. You don't have to open a browser tab to check if a specific user group exists in Heap because the Windsurf agent pulls the list directly.

Setup guide

Set up Heap MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Heap MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Heap payment history." If connected, Cascade will call the Heap tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "heap-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Heap. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Heap now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Heap MCP in Windsurf

Open your settings in Windsurf and navigate to the Cascade MCP configuration panel. Add the Heap server under the `mcpServers` key in your JSON configuration. Cascade immediately discovers the Heap tools and lets you query user metrics.

Yes, Cascade calls `get_event_definitions` to inspect your active Heap actions while you write code in Windsurf. This lets Cascade suggest code changes based on actual user drop-off points in your Heap funnel. You get data-driven code suggestions without leaving your active Windsurf file.

Cascade uses `bulk_add_user_properties` to update multiple test accounts in Heap at once during your Windsurf session. This prevents your Windsurf editor from freezing up during heavy testing sessions. Cascade runs these batches in the background while you continue coding in Windsurf.

The `get_my_profile` tool fails immediately and alerts Cascade of the authentication error in Windsurf. You will see a clear Heap connection error message in your Windsurf output panel. Simply update your Heap credentials in the Windsurf configuration file to restore the connection.

All Heap event logs and user profiles remain sandboxed inside Vinkius's isolated runtime environment during your Windsurf sessions. No Heap credentials or behavioral metrics are stored on external logging servers by Cascade. This MCP architecture ensures that sensitive Heap behavioral metrics never touch third-party storage.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript