Merge branch 'main' into jerrylin-mparticlefix

jerrylin3321 · web-flow · commit f2257ebda663 · 2026-03-10T16:43:47.000-07:00
diff --git a/pages/docs/features/mcp.mdx b/pages/docs/features/mcp.mdx
@@ -22,17 +22,23 @@ The MCP integration provides access to all core Mixpanel analysis capabilities t
 
 ### Analytics Functions
 
-- Segmentation: Event counts and unique users with filtering and grouping (`Run-Segmentation-Query`)
-- Funnels: Conversion rate analysis across user journeys (`Run-Funnels-Query`)
-- Retention: User engagement and return behavior tracking (`Run-Retention-Query`)
-- Frequency: User engagement patterns and usage intensity (`Run-Frequency-Query`)
+- Run Query: Execute insights, funnels, flows, and retention queries and return data points (`Run-Query`)
+- Query Schema: Get the full instructions and JSON schema for building a query (`Get-Query-Schema`)
+- Get Report: Retrieve a saved report from a Mixpanel project, optionally including results (`Get-Report`)
+
+### Dashboards
+
+- Create Dashboard: Create a new dashboard with rows of text cards and reports (`Create-Dashboard`)
+- List Dashboards: Browse dashboards in a project, with optional title search (`List-Dashboards`)
+- Get Dashboard: Retrieve detailed information about a specific dashboard (`Get-Dashboard`)
 
 ### Data Discovery & Exploration
 
 - Project Management: Access projects and workspace information (`Get-Projects`)
 - Event Discovery: Browse all available events in your project (`Get-Events`)
 - Property Names: Explore properties available for events or users (`Get-Property-Names`)
 - Property Values: Discover specific values for event or user properties (`Get-Property-Values`)
+- Property Details: Retrieve full property metadata (`Get-Property`)
 - Data Quality: Get and filter data quality issues by event, property, type, or date range (`Get-Issues`)
 - Lexicon Integration: Get direct links to event or property definitions in Mixpanel Lexicon (`Get-Lexicon-URL`)
 
@@ -126,7 +132,7 @@ For additional information on setting up Claude connectors, see [Claude's connec
 **Setup Steps:**
 1. Open Claude desktop app
 2. Navigate to **Settings** (from window nav bar) → **Developer** → **Edit Config**
-3. Add the following configuration:
+3. Add the following configuration (replace the URL with `https://mcp-eu.mixpanel.com/mcp` for EU or `https://mcp-in.mixpanel.com/mcp` for IN):
 
 ```json
 {
@@ -136,7 +142,7 @@ For additional information on setting up Claude connectors, see [Claude's connec
       "args": [
         "-y",
         "mcp-remote",
-        "https://mcp.mixpanel.com/mcp", // or use mcp-eu.mixpanel.com/mcp for EU, mcp-in.mixpanel.com/mcp for IN
+        "https://mcp.mixpanel.com/mcp",
         "--allow-http"
       ]
     }
@@ -146,17 +152,17 @@ For additional information on setting up Claude connectors, see [Claude's connec
 
 4. Run authorization command in terminal:
 ```bash
-npx -y mcp-remote https://mcp.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp.mixpanel.com/mcp --allow-http
 ```
 
 For EU,
 ```bash
-npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --allow-http
 ```
 
 For IN,
 ```bash
-npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --allow-http
 ```
 
 5. Complete Mixpanel authorization via the provided link
@@ -165,13 +171,13 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
 
 ### Option 3: Cursor
 **Additional Requirements:**
-- Cursor application  
+- Cursor application
 - Command line access
 
 **Setup Steps:**
 1. Open Cursor application
 2. Navigate to **Cursor Settings** → **MCP & Integrations** → **MCP Tools** → **New MCP Server**
-3. This opens MCP.json where you paste the following configuration:
+3. This opens MCP.json where you paste the following configuration (replace the URL with `https://mcp-eu.mixpanel.com/mcp` for EU or `https://mcp-in.mixpanel.com/mcp` for IN):
 
 ```json
 {
@@ -181,7 +187,7 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
       "args": [
         "-y",
         "mcp-remote",
-        "https://mcp.mixpanel.com/mcp", // or use mcp-eu.mixpanel.com/mcp for EU, mcp-in.mixpanel.com/mcp for IN
+        "https://mcp.mixpanel.com/mcp",
         "--allow-http"
       ]
     }
@@ -191,17 +197,17 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
 
 4. Run authorization command in terminal:
 ```bash
-npx -y mcp-remote https://mcp.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp.mixpanel.com/mcp --allow-http
 ```
 
 For EU,
 ```bash
-npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --allow-http
 ```
 
 For IN,
 ```bash
-npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --allow-http
 ```
 
 
@@ -223,28 +229,28 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
    ```
 3. Configure Mixpanel MCP as a remote server and authorize:
    ```bash
-   npx -y mcp-remote https://mcp.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+   npx -y mcp-remote https://mcp.mixpanel.com/mcp --allow-http
    ```
 
    For EU,
    ```bash
-   npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+   npx -y mcp-remote https://mcp-eu.mixpanel.com/mcp --allow-http
    ```
 
    For IN,
    ```bash
-   npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata '{ "scope": "projects analysis events insights segmentation retention data:read funnels flows data_definitions" }' --allow-http
+   npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --allow-http
    ```
 
    Running this command will provide a link in your terminal to authorize your access with Mixpanel. Follow the authorization steps in your browser. After logging in via OAuth, you should see a confirmation message.
 
-4. **Verify Configuration (or Create It Manually):**  
+4. **Verify Configuration (or Create It Manually):**
    After authorization, your `settings.json` file for the Gemini CLI should be updated automatically. You can find this file at `~/.gemini/settings.json`. To check, run:
    ```bash
    ls -la ~/.gemini
    cat ~/.gemini/settings.json
    ```
-   The contents should be similar to the following:
+   The contents should be similar to the following (replace the URL with `https://mcp-eu.mixpanel.com/mcp` for EU or `https://mcp-in.mixpanel.com/mcp` for IN):
    ```json
    {
      "theme": "Default",
@@ -255,7 +261,7 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
          "args": [
            "-y",
            "mcp-remote",
-           "https://mcp.mixpanel.com/mcp",  // or use mcp-eu.mixpanel.com/mcp for EU, mcp-in.mixpanel.com/mcp for IN
+           "https://mcp.mixpanel.com/mcp",
            "--allow-http"
          ]
        }
@@ -265,7 +271,7 @@ npx -y mcp-remote https://mcp-in.mixpanel.com/mcp --static-oauth-client-metadata
    ```
    This configuration ensures that the Gemini CLI knows how to connect to the Mixpanel remote server.
    If `settings.json` is not available, create it manually using the same contents as above.
-   
+
 
 5. Complete Mixpanel authorization via the provided link (if not already done).
 6. Run the Gemini CLI
@@ -350,6 +356,16 @@ The following scopes are **mandatory** — connections will fail without all of
 projects analysis events insights segmentation retention data:read funnels flows data_definitions
 ```
 
+The following scopes are **optional** — they enable additional features when granted:
+
+```
+dashboard_reports bookmarks user_details
+```
+
+<Callout type="info">
+  To request only a subset of scopes, pass `--static-oauth-client-metadata '{ "scope": "..." }'` to `npx mcp-remote`. Otherwise, all available scopes are requested automatically.
+</Callout>
+
 ---
 
 ## Use Case Examples
@@ -398,7 +414,7 @@ projects analysis events insights segmentation retention data:read funnels flows
 - Instant insights without dashboard complexity
 - Accessible to non-technical stakeholders
 
-**Enhanced Productivity**  
+**Enhanced Productivity**
 - Reduce time-to-insight from minutes to seconds
 - Eliminate context switching between tools
 - Enable real-time decision making
@@ -457,3 +473,5 @@ projects analysis events insights segmentation retention data:read funnels flows
 - **Authorization fails:** Ensure proper Mixpanel account permissions
 - **Desktop app issues:** Restart application after configuration changes
 - **Free user limitations:** Remote URL integrations only supported in desktop app
+- **"MCP access is not enabled for this project":** This means MCP has not been enabled at the organization level. Ask your **organization administrator** to enable MCP access in **Settings > Org > Overview**. Note that after the admin enables access, it may take up to 15 minutes for the change to take effect.
+- **"Missing scope" error:** This usually means your cached authorization was created with an outdated scope list. To fix this, clear your cached auth data by deleting the `.mcp-auth` folder in the directory where you ran the authorization command, then re-run the authorization command to get a fresh token with all available scopes. If you previously used `--static-oauth-client-metadata` in your authorization command, either remove that flag so the client auto-discovers all scopes from the server or update the scopes used for that parameter for explicit control of scopes requested.
diff --git a/pages/docs/session-replay.mdx b/pages/docs/session-replay.mdx
@@ -80,6 +80,27 @@ The Replay Feed on the left of the player also allows you to:
 - See a feed of events that occurred during each replay
 - Display properties and their values within the event feed
 
+### Magic Playlists
+
+Magic Playlists allow you to save playlists of replays based on events or properties, making it easy to revisit groups of replays that matter to you over time. This feature helps solve common pain points:
+
+- **Save interesting replays**: No need to repeatedly recreate replay searches
+- **Dynamic playlists**: Create playlists based on your Mixpanel events and properties that automatically update as new replays meet your criteria
+- **AI-powered insights**: Get AI text summaries that identify key patterns and insights across numerous replays at once
+
+<Callout type="info">
+  AI summaries for Magic Playlists are currently in beta and publicly available for all customers using Magic Playlists.
+</Callout>
+
+To create a Magic Playlist:
+
+1. Access Session Replay from the side navigation in your Mixpanel project
+2. Configure filters based on events, properties, or custom time ranges
+3. Save the playlist, which will remember the filters you've applied
+4. Select a destination Mixpanel board where you want the playlist to appear
+
+Once saved, your Magic Playlist will appear as a playlist card on your selected board. Any time new replays meet your saved criteria, they will automatically appear in your playlist, keeping your board up-to-date with the replays that matter most to you.
+
 ## Best Practices
 
 Session Replay is a powerful way to understand and debug user behavior by showing exactly what users see on their screens. This visibility is core to its value—but also introduces inherent privacy and security risks, especially when sensitive information appears in the UI.
diff --git a/pages/docs/session-replay/heatmaps.mdx b/pages/docs/session-replay/heatmaps.mdx
@@ -28,7 +28,7 @@ To function, Heatmaps require Session Replay to be enabled, as they rely on sess
 Heatmaps only capture data during sessions with recorded replays. If a page has limited replay coverage, the Heatmap may not offer meaningful insights.
 
 <Callout type="warning">
-  When clicks occur very close to page navigation events, the heatmap may occasionally show clicks on the wrong page. This happens because the timing between page changes and click events may not align perfectly. If you notice clicks appearing on the wrong page, try using a different [backdrop](#backdrops) to find the correct page state.
+  When clicks occur very close to page navigation events, the heatmap may occasionally show clicks on the wrong page. This happens because the timing between page changes and click events may not align perfectly. If you notice clicks appearing on the wrong page, try using a different [UI State](#ui-states) to find the correct page state.
 </Callout>
 
 ### Implementation
@@ -88,9 +88,9 @@ mixpanel.init('YOUR_PROJECT_TOKEN', {
 
 ![heatmap_rename.png](/heatmap_rename.png)
 
-4. Rotate through backdrops to view different states of your application for the same URL.
+4. Rotate through UI States to view different states of your application for the same URL.
 
-![heatmap_backdrops.png](/heatmap_backdrops.png)
+![UI States view](/heatmap_backdrops.png)
 
 5. Use the Click Map and Heatmap toggles to show or hide each view. Click Maps help you see exactly which elements users click, which can clarify any inaccuracies in traditional heatmaps caused by dynamic page elements.
 
@@ -116,12 +116,12 @@ Once enabled, Goal Mode highlights the UI elements driving the most conversions,
   Goal Mode works with any of your existing events and properties directly out of the box—no additional setup required.
 </Callout>
 
-### Backdrops
+### UI States
 
-Backdrops are snapshots of your application in various states (such as a modal open, a menu expanded, or different page layouts). Backdrops are pulled from session replays that match the URL you're analyzing, helping you understand how different views or UI states affect user interactions.
+UI States are snapshots of your application in various states (such as a modal open, a menu expanded, or different page layouts). UI States are pulled from session replays that match the URL you're analyzing, helping you understand how different views or UI states affect user interactions.
 
-Backdrops are subject to the same retention policies as your session replays. Once a session replay expires, it can no longer be used as a backdrop. If you don't see enough backdrops (or can't find the specific view or state you're looking for), consider increasing your session replay sampling rate to capture a wider set of application states.
+UI States are subject to the same retention policies as your session replays. Once a session replay expires, it can no longer be used as a UI State. If you don't see enough UI States (or can't find the specific view or state you're looking for), consider increasing your session replay sampling rate to capture a wider set of application states.
 
 <Callout type="warning">
-  Heatmaps only track scrolling on the main page (window). If your site scrolls inside a nested container (like a div with its own scrollbar), heatmaps and interactive mode may not display data correctly. The interactive backdrops feature lets you customize your backdrop, but click positions within nested scrollable elements will still not be fully reflected.
+  Heatmaps only track scrolling on the main page (window). If your site scrolls inside a nested container (like a div with its own scrollbar), heatmaps and interactive mode may not display data correctly. The interactive UI States feature lets you customize your UI State, but click positions within nested scrollable elements will still not be fully reflected.
 </Callout>
diff --git a/pages/docs/tracking-methods/sdks/javascript/javascript-replay.mdx b/pages/docs/tracking-methods/sdks/javascript/javascript-replay.mdx
@@ -333,43 +333,19 @@ analytics.addSourceMiddleware(({ payload, next, integrations }) => {
 
 ### mParticle: Web SDK
 
-mParticle's Web SDK has a `.getDeviceId()` method which can be used to [retrieve the device_id](https://docs.mparticle.com/developers/client-sdks/web/initialization/#device-id-device-application-stamp). In the following example, we use this method to bind mParticle's device_id to Mixpanel's device_id, as well as patching [logPageView()](https://docs.mparticle.com/developers/sdk/web/core-apidocs/classes/mParticle%20&%20mParticleInstance.html#method_logPageView) and [logEvent()](https://docs.mparticle.com/developers/sdk/web/core-apidocs/classes/mParticle%20&%20mParticleInstance.html#method_logEvent) to include session replay properties on all mParticle events. 
+mParticle offers a direct integration for Session Replay with Mixpanel. You can configure Session Replay settings directly in your mParticle connection settings, which automatically handles session replay properties on all events.
 
-This configuration assumes you are [forwarding web requests server side](https://docs.mparticle.com/integrations/mixpanel/event/#connection-settings) in the connection settings.
+#### Direct Integration (Recommended)
 
-```javascript Javascript
-mixpanel.init('MIXPANEL-PROJECT-TOKEN', {
-	record_sessions_percent: 10,
-	loaded: function (mixpanel) {
-		window.mParticle.ready(function() {
-			const mParticle_device_id = mParticle.getDeviceId();
-			if (mParticle_device_id) {
-				mixpanel.register({ $device_id: mParticle_device_id, distinct_id : "$device:"+mParticle_device_id });
-			}
- 
-			// Patch logEvent and logPageView to include sessionReplayProperties
-			const originalLogEvent = mParticle.logEvent;
-			mParticle.logEvent = function (eventName, eventType, eventAttributes, flags, opts) {
-				const sessionReplayProperties = mixpanel.get_session_recording_properties();
-				eventAttributes = {
-					...eventAttributes,
-					...sessionReplayProperties,
-				};
-				originalLogEvent(eventName, eventType, eventAttributes, flags, opts);
-			};
-			const originalLogPageView = mParticle.logPageView;
-			mParticle.logPageView = function (eventName, eventAttributes, flags, opts) {
-				const sessionReplayProperties = mixpanel.get_session_recording_properties();
-				eventAttributes = {
-					...eventAttributes,
-					...sessionReplayProperties,
-				};
-				originalLogPageView(eventName, eventAttributes, flags, opts);
-			};
-		});
-	}
-});
-```
+To use the direct integration:
+
+1. Ensure you have the mParticle Mixpanel Web integration enabled for your web workspace. This will load the Mixpanel JavaScript SDK and Session Replay on your site automatically via mParticle (no separate SDK install in your app code is required).
+2. Configure Session Replay settings in your [mParticle Mixpanel connection settings](https://docs.mparticle.com/integrations/mixpanel/event/#connection-settings), including:
+   - **Session Recording Percentage**: Percentage of SDK initializations that will qualify for replay data capture
+   - **Record Heatmap Data**: Enable heatmap, rage click, and dead click collection
+   - Additional privacy and configuration options as needed
+
+The direct integration automatically includes session replay properties (`$mp_replay_id`) on all events forwarded through mParticle, without requiring any additional code changes.
 
 ### Rudderstack: Cloud Mode
 
