You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by mi...@apache.org on 2026/06/04 18:13:44 UTC

(superset) 01/01: fix(mcp): generate durable explore permalink URL instead of ephemeral form_data_key

This is an automated email from the ASF dual-hosted git repository.

aminghadersohi pushed a commit to branch mcp-chart-explore-url
in repository https://gitbox.apache.org/repos/asf/superset.git

commit 62fae8c4938c93687d57407b8263b793a6d646b2
Author: Amin Ghadersohi <am...@gmail.com>
AuthorDate: Thu Jun 4 18:13:20 2026 +0000

    fix(mcp): generate durable explore permalink URL instead of ephemeral form_data_key
    
    The `generate_explore_link` MCP tool previously returned a URL like
    `/explore/?form_data_key=<key>` backed by Redis cache (~24h expiry).
    When the key expired the URL became unreachable, preventing LLMs from
    iteratively building and sharing charts.
    
    This commit changes the URL strategy:
    1. Try `CreateExplorePermalinkCommand` first (DB-backed key-value store,
       does not expire) → `/explore/p/<key>/`
    2. Fall back to `MCPCreateFormDataCommand` (Redis cache) on permalink
       failure → `/explore/?form_data_key=<key>`
    3. Fall back to plain dataset URL on both failing.
    
    The tool response now includes a `permalink_key` field (populated when
    the durable permalink path is used) alongside the existing `form_data_key`
    (populated only in the Redis-fallback case).
    
    `extract_permalink_key_from_url()` added to `chart_helpers.py`.
    Tests updated to mock `CreateExplorePermalinkCommand.run` by default and
    cover both the permalink path and each fallback tier.
---
 superset/mcp_service/chart/chart_helpers.py        |  13 +
 superset/mcp_service/chart/chart_utils.py          |  34 ++-
 .../explore/tool/generate_explore_link.py          |  22 +-
 .../explore/tool/test_generate_explore_link.py     | 306 +++++++++++----------
 4 files changed, 217 insertions(+), 158 deletions(-)

diff --git a/superset/mcp_service/chart/chart_helpers.py b/superset/mcp_service/chart/chart_helpers.py
index f5ccc4102a4..dd1d6b647ab 100644
--- a/superset/mcp_service/chart/chart_helpers.py
+++ b/superset/mcp_service/chart/chart_helpers.py
@@ -26,6 +26,7 @@ URL parameter extraction. Config mapping logic lives in chart_utils.py.
 from __future__ import annotations
 
 import logging
+import re
 from typing import Any, TYPE_CHECKING
 from urllib.parse import parse_qs, urlparse
 
@@ -697,6 +698,18 @@ def extract_form_data_key_from_url(url: str | None) -> str | None:
     return values[0] if values else None
 
 
+def extract_permalink_key_from_url(url: str | None) -> str | None:
+    """Extract the permalink key from an explore permalink URL.
+
+    Matches the /explore/p/<key>/ pattern produced by CreateExplorePermalinkCommand.
+    Returns the key, or None if the URL does not follow that pattern.
+    """
+    if not url:
+        return None
+    match = re.search(r"/explore/p/([^/]+)/?", url)
+    return match.group(1) if match else None
+
+
 def _match_adhoc_by_subject(
     adhoc_filters: Any, column: str | None
 ) -> tuple[str | None, Any] | None:
diff --git a/superset/mcp_service/chart/chart_utils.py b/superset/mcp_service/chart/chart_utils.py
index a52d69e34a8..63e3b3b49d1 100644
--- a/superset/mcp_service/chart/chart_utils.py
+++ b/superset/mcp_service/chart/chart_utils.py
@@ -158,13 +158,21 @@ def validate_chart_dataset(
 
 
 def generate_explore_link(dataset_id: int | str, form_data: Dict[str, Any]) -> str:
-    """Generate an explore link for the given dataset and form data."""
+    """Generate an explore link for the given dataset and form data.
+
+    Prefers a durable explore permalink (DB-backed key-value store, does not
+    expire) over an ephemeral form_data_key (Redis cache, expires in ~24h).
+    Falls back to the form_data_key approach if permalink creation fails, then
+    to a plain dataset URL as a last resort.
+    """
     from sqlalchemy.exc import SQLAlchemyError
 
     from superset.commands.exceptions import CommandException
     from superset.commands.explore.form_data.parameters import CommandParameters
+    from superset.commands.explore.permalink.create import CreateExplorePermalinkCommand
     from superset.daos.dataset import DatasetDAO
     from superset.exceptions import SupersetException
+    from superset.explore.permalink.exceptions import ExplorePermalinkCreateFailedError
     from superset.mcp_service.commands.create_form_data import (
         MCPCreateFormDataCommand,
     )
@@ -200,7 +208,25 @@ def generate_explore_link(dataset_id: int | str, form_data: Dict[str, Any]) -> s
             "datasource": f"{numeric_dataset_id}__table",
         }
 
-        # Try to create form_data in cache using MCP-specific CreateFormDataCommand
+        # Try durable permalink first (DB-backed key-value store, does not expire)
+        try:
+            state = {"formData": form_data_with_datasource}
+            permalink_key = CreateExplorePermalinkCommand(state=state).run()
+            return f"{base_url}/explore/p/{permalink_key}/"
+        except (
+            ExplorePermalinkCreateFailedError,
+            SQLAlchemyError,
+            KeyError,
+            ValueError,
+            AttributeError,
+            TypeError,
+        ) as permalink_e:
+            logger.debug(
+                "Permalink generation failed, falling back to form_data_key: %s",
+                permalink_e,
+            )
+
+        # Fall back to ephemeral form_data_key (Redis-backed cache)
         cmd_params = CommandParameters(
             datasource_type=DatasourceType.TABLE,
             datasource_id=numeric_dataset_id,
@@ -208,11 +234,7 @@ def generate_explore_link(dataset_id: int | str, form_data: Dict[str, Any]) -> s
             tab_id=None,
             form_data=json.dumps(form_data_with_datasource),
         )
-
-        # Create the form_data cache entry and get the key
         form_data_key = MCPCreateFormDataCommand(cmd_params).run()
-
-        # Return URL with just the form_data_key
         return f"{base_url}/explore/?form_data_key={form_data_key}"
 
     except (
diff --git a/superset/mcp_service/explore/tool/generate_explore_link.py b/superset/mcp_service/explore/tool/generate_explore_link.py
index 68ed36c037a..fafaeaba461 100644
--- a/superset/mcp_service/explore/tool/generate_explore_link.py
+++ b/superset/mcp_service/explore/tool/generate_explore_link.py
@@ -30,7 +30,10 @@ from superset_core.mcp.decorators import tool, ToolAnnotations
 
 from superset.extensions import event_logger
 from superset.mcp_service.auth import has_dataset_access
-from superset.mcp_service.chart.chart_helpers import extract_form_data_key_from_url
+from superset.mcp_service.chart.chart_helpers import (
+    extract_form_data_key_from_url,
+    extract_permalink_key_from_url,
+)
 from superset.mcp_service.chart.chart_utils import (
     generate_explore_link as generate_url,
     get_table_chart_type_label,
@@ -135,6 +138,7 @@ async def generate_explore_link(
                 return {
                     "url": "",
                     "form_data": {},
+                    "permalink_key": None,
                     "form_data_key": None,
                     "chart_type_label": None,
                     "error": (
@@ -154,6 +158,7 @@ async def generate_explore_link(
                 return {
                     "url": "",
                     "form_data": {},
+                    "permalink_key": None,
                     "form_data_key": None,
                     "chart_type_label": None,
                     "error": (
@@ -178,6 +183,7 @@ async def generate_explore_link(
             return {
                 "url": default_url,
                 "form_data": {},
+                "permalink_key": None,
                 "form_data_key": None,
                 "chart_type_label": None,
                 "error": None,
@@ -248,6 +254,7 @@ async def generate_explore_link(
             return {
                 "url": "",
                 "form_data": form_data,
+                "permalink_key": None,
                 "form_data_key": None,
                 "chart_type_label": None,
                 "error": error_payload,
@@ -262,19 +269,23 @@ async def generate_explore_link(
                 dataset_id=request.dataset_id, form_data=form_data
             )
 
-        # Extract form_data_key from the explore URL
-        form_data_key = extract_form_data_key_from_url(explore_url)
+        # Extract permalink_key (durable) or fall back to form_data_key (ephemeral)
+        permalink_key = extract_permalink_key_from_url(explore_url)
+        form_data_key = (
+            extract_form_data_key_from_url(explore_url) if not permalink_key else None
+        )
 
         await ctx.report_progress(4, 4, "URL generation complete")
         await ctx.info(
             "Explore link generated successfully: url_length=%s, dataset_id=%s, "
-            "form_data_key=%s"
-            % (len(explore_url or ""), request.dataset_id, form_data_key)
+            "permalink_key=%s, form_data_key=%s"
+            % (len(explore_url or ""), request.dataset_id, permalink_key, form_data_key)
         )
 
         return {
             "url": explore_url,
             "form_data": form_data,
+            "permalink_key": permalink_key,
             "form_data_key": form_data_key,
             "chart_type_label": get_table_chart_type_label(form_data.get("viz_type")),
             "error": None,
@@ -293,6 +304,7 @@ async def generate_explore_link(
         return {
             "url": "",
             "form_data": {},
+            "permalink_key": None,
             "form_data_key": None,
             "chart_type_label": None,
             "error": f"Failed to generate explore link: {str(e)}",
diff --git a/tests/unit_tests/mcp_service/explore/tool/test_generate_explore_link.py b/tests/unit_tests/mcp_service/explore/tool/test_generate_explore_link.py
index a4dc86f86a3..6329a969e10 100644
--- a/tests/unit_tests/mcp_service/explore/tool/test_generate_explore_link.py
+++ b/tests/unit_tests/mcp_service/explore/tool/test_generate_explore_link.py
@@ -49,6 +49,13 @@ generate_explore_link_module = importlib.import_module(
 logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)
 
+_PERMALINK_PATCH = (
+    "superset.commands.explore.permalink.create.CreateExplorePermalinkCommand.run"
+)
+_FORM_DATA_PATCH = (
+    "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
+)
+
 
 @pytest.fixture
 def mcp_server():
@@ -100,6 +107,17 @@ def mock_webdriver_baseurl(app_context):
     current_app.config["WEBDRIVER_BASEURL_USER_FRIENDLY"] = original_value
 
 
+@pytest.fixture(autouse=True)
+def mock_permalink_creation():
+    """Create durable permalink by default.
+
+    Override in individual tests that need fallback-to-form_data_key or
+    fallback-to-basic-URL behaviour by patching _PERMALINK_PATCH to raise.
+    """
+    with patch(_PERMALINK_PATCH, return_value="test_permalink_key"):
+        yield
+
+
 def _mock_dataset(id: int = 1) -> Mock:
     """Create a mock dataset object with columns and db_engine_spec."""
     from superset.utils.core import ColumnSpec, GenericDataType
@@ -132,15 +150,11 @@ class TestGenerateExploreLink:
     """Comprehensive tests for generate_explore_link MCP tool."""
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_table_explore_link_minimal(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link for minimal table chart."""
-        mock_create_form_data.return_value = "test_form_data_key_123"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         config = TableChartConfig(
@@ -156,21 +170,18 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=test_form_data_key_123"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
+            assert result.data["permalink_key"] == "test_permalink_key"
+            assert result.data["form_data_key"] is None
             assert result.data["chart_type_label"] == "table chart"
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_table_explore_link_with_features(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link for table chart with features."""
-        mock_create_form_data.return_value = "comprehensive_key_456"
         mock_find_dataset.return_value = _mock_dataset(id=5)
 
         config = TableChartConfig(
@@ -196,21 +207,18 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=comprehensive_key_456"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
+            assert result.data["permalink_key"] == "test_permalink_key"
+            assert result.data["form_data_key"] is None
             assert result.data["chart_type_label"] == "table chart"
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_ag_grid_table_explore_link_label(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ) -> None:
         """Test generating explore link reports AG Grid table label."""
-        mock_create_form_data.return_value = "ag_grid_key_123"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         config = TableChartConfig(
@@ -229,15 +237,11 @@ class TestGenerateExploreLink:
             assert result.data["chart_type_label"] == "interactive table chart"
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_line_chart_explore_link(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link for line chart."""
-        mock_create_form_data.return_value = "line_chart_key_789"
         mock_find_dataset.return_value = _mock_dataset(id=3)
 
         config = XYChartConfig(
@@ -263,21 +267,14 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=line_chart_key_789"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
             assert result.data["chart_type_label"] is None
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
-    async def test_generate_bar_chart_explore_link(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
-    ):
+    async def test_generate_bar_chart_explore_link(self, mock_find_dataset, mcp_server):
         """Test generating explore link for bar chart."""
-        mock_create_form_data.return_value = "bar_chart_key_abc"
         mock_find_dataset.return_value = _mock_dataset(id=7)
 
         config = XYChartConfig(
@@ -298,20 +295,15 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=bar_chart_key_abc"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_area_chart_explore_link(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link for area chart."""
-        mock_create_form_data.return_value = "area_chart_key_def"
         mock_find_dataset.return_value = _mock_dataset(id=2)
 
         config = XYChartConfig(
@@ -335,20 +327,15 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=area_chart_key_def"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_scatter_chart_explore_link(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link for scatter chart."""
-        mock_create_form_data.return_value = "scatter_chart_key_ghi"
         mock_find_dataset.return_value = _mock_dataset(id=4)
 
         config = XYChartConfig(
@@ -370,22 +357,71 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=scatter_chart_key_ghi"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
+    @patch(_PERMALINK_PATCH)
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
+    @patch(_FORM_DATA_PATCH)
     @pytest.mark.asyncio
-    async def test_generate_explore_link_cache_failure_fallback(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+    async def test_generate_explore_link_permalink_fails_fallback_to_form_data_key(
+        self,
+        mock_create_form_data,
+        mock_find_dataset,
+        mock_create_permalink,
+        mcp_server,
     ):
-        """Test fallback when form_data cache creation fails."""
+        """When permalink creation fails, fall back to ephemeral form_data_key URL."""
+        from superset.explore.permalink.exceptions import (
+            ExplorePermalinkCreateFailedError,
+        )
+
         mock_find_dataset.return_value = _mock_dataset(id=1)
+        mock_create_permalink.side_effect = ExplorePermalinkCreateFailedError(
+            "DB unavailable"
+        )
+        mock_create_form_data.return_value = "fallback_form_data_key"
+
+        config = TableChartConfig(
+            chart_type="table", columns=[ColumnRef(name="test_col")]
+        )
+        request = GenerateExploreLinkRequest(dataset_id="1", config=config)
+
+        async with Client(mcp_server) as client:
+            result = await client.call_tool(
+                "generate_explore_link", {"request": request.model_dump()}
+            )
+
+            assert result.data["error"] is None
+            assert (
+                result.data["url"]
+                == "http://localhost:9001/explore/?form_data_key=fallback_form_data_key"
+            )
+            assert result.data["form_data_key"] == "fallback_form_data_key"
+            assert result.data["permalink_key"] is None
+            mock_create_form_data.assert_called_once()
+
+    @patch(_PERMALINK_PATCH)
+    @patch("superset.daos.dataset.DatasetDAO.find_by_id")
+    @patch(_FORM_DATA_PATCH)
+    @pytest.mark.asyncio
+    async def test_generate_explore_link_both_fail_fallback_to_basic_url(
+        self,
+        mock_create_form_data,
+        mock_find_dataset,
+        mock_create_permalink,
+        mcp_server,
+    ):
+        """When both permalink and form_data_key fail, fall back to basic URL."""
         from superset.commands.exceptions import CommandException
+        from superset.explore.permalink.exceptions import (
+            ExplorePermalinkCreateFailedError,
+        )
 
+        mock_find_dataset.return_value = _mock_dataset(id=1)
+        mock_create_permalink.side_effect = ExplorePermalinkCreateFailedError(
+            "DB unavailable"
+        )
         mock_create_form_data.side_effect = CommandException("Cache storage failed")
 
         config = TableChartConfig(
@@ -398,28 +434,31 @@ class TestGenerateExploreLink:
                 "generate_explore_link", {"request": request.model_dump()}
             )
 
-            # Should fallback to basic URL format
             assert result.data["error"] is None
             assert (
                 result.data["url"]
                 == "http://localhost:9001/explore/?datasource_type=table&datasource_id=1"
             )
 
+    @patch(_PERMALINK_PATCH)
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
+    @patch(_FORM_DATA_PATCH)
     @pytest.mark.asyncio
     async def test_generate_explore_link_database_lock_fallback(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self,
+        mock_create_form_data,
+        mock_find_dataset,
+        mock_create_permalink,
+        mcp_server,
     ):
-        """Test fallback when database is locked."""
+        """When permalink fails with SQLAlchemy error, fall back to form_data_key."""
         from sqlalchemy.exc import OperationalError
 
         mock_find_dataset.return_value = _mock_dataset(id=5)
-        mock_create_form_data.side_effect = OperationalError(
+        mock_create_permalink.side_effect = OperationalError(
             "database is locked", None, None
         )
+        mock_create_form_data.return_value = "lock_fallback_key"
 
         config = XYChartConfig(
             chart_type="xy",
@@ -434,23 +473,18 @@ class TestGenerateExploreLink:
                 "generate_explore_link", {"request": request.model_dump()}
             )
 
-            # Should fallback to basic dataset URL
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?datasource_type=table&datasource_id=5"
+                == "http://localhost:9001/explore/?form_data_key=lock_fallback_key"
             )
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_explore_link_with_many_columns(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link with many columns."""
-        mock_create_form_data.return_value = "many_columns_key"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         # Create 15 columns
@@ -474,20 +508,15 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=many_columns_key"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_explore_link_with_many_filters(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test generating explore link with many filters."""
-        mock_create_form_data.return_value = "many_filters_key"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         # Create 12 filters
@@ -517,20 +546,15 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=many_filters_key"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_explore_link_url_format_consistency(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
-        """Test that all generated URLs follow consistent format."""
-        mock_create_form_data.return_value = "consistency_test_key"
+        """Test that all generated URLs follow consistent permalink format."""
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         configs = [
@@ -569,23 +593,19 @@ class TestGenerateExploreLink:
                     "generate_explore_link", {"request": request.model_dump()}
                 )
 
-                # All URLs should follow the same format
+                # All URLs should follow the same permalink format
                 assert (
                     result.data["url"]
-                    == "http://localhost:9001/explore/?form_data_key=consistency_test_key"
+                    == "http://localhost:9001/explore/p/test_permalink_key/"
                 )
                 assert result.data["error"] is None
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_explore_link_dataset_id_types(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test explore link generation with different dataset_id formats."""
-        mock_create_form_data.return_value = "dataset_test_key"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         config = TableChartConfig(
@@ -604,19 +624,15 @@ class TestGenerateExploreLink:
                 assert result.data["error"] is None
                 assert (
                     result.data["url"]
-                    == "http://localhost:9001/explore/?form_data_key=dataset_test_key"
+                    == "http://localhost:9001/explore/p/test_permalink_key/"
                 )
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_explore_link_complex_configuration(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test explore link generation with complex chart configuration."""
-        mock_create_form_data.return_value = "complex_config_key"
         mock_find_dataset.return_value = _mock_dataset(id=10)
 
         config = XYChartConfig(
@@ -648,22 +664,30 @@ class TestGenerateExploreLink:
             assert result.data["error"] is None
             assert (
                 result.data["url"]
-                == "http://localhost:9001/explore/?form_data_key=complex_config_key"
+                == "http://localhost:9001/explore/p/test_permalink_key/"
             )
-            mock_create_form_data.assert_called_once()
 
+    @patch(_PERMALINK_PATCH)
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
+    @patch(_FORM_DATA_PATCH)
     @pytest.mark.asyncio
     async def test_fallback_url_different_datasets(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self,
+        mock_create_form_data,
+        mock_find_dataset,
+        mock_create_permalink,
+        mcp_server,
     ):
-        """Test fallback URLs are correct for different dataset IDs."""
-        mock_find_dataset.return_value = _mock_dataset(id=1)
+        """When both fallbacks fail, basic URL uses the correct dataset_id."""
         from superset.commands.exceptions import CommandException
+        from superset.explore.permalink.exceptions import (
+            ExplorePermalinkCreateFailedError,
+        )
 
+        mock_find_dataset.return_value = _mock_dataset(id=1)
+        mock_create_permalink.side_effect = ExplorePermalinkCreateFailedError(
+            "Always fail for fallback testing"
+        )
         mock_create_form_data.side_effect = CommandException(
             "Always fail for fallback testing"
         )
@@ -680,7 +704,10 @@ class TestGenerateExploreLink:
                 )
 
                 # Should fallback to basic URL with correct dataset_id
-                expected_url = f"http://localhost:9001/explore/?datasource_type=table&datasource_id={dataset_id}"
+                expected_url = (
+                    f"http://localhost:9001/explore/?datasource_type=table"
+                    f"&datasource_id={dataset_id}"
+                )
                 assert result.data["error"] is None
                 assert result.data["url"] == expected_url
 
@@ -720,22 +747,21 @@ class TestGenerateExploreLink:
                 assert result.data["url"] == ""
                 assert result.data["form_data"] == {}
                 assert result.data["form_data_key"] is None
+                assert result.data["permalink_key"] is None
                 assert result.data["chart_type_label"] is None
                 assert "Invalid config structure" in result.data["error"]
         finally:
             # Restore original function
             explore_module.map_config_to_form_data = original_func
 
+    @patch(_PERMALINK_PATCH)
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
-    async def test_generate_explore_link_returns_form_data_key(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+    async def test_generate_explore_link_returns_permalink_key(
+        self, mock_find_dataset, mock_create_permalink, mcp_server
     ):
-        """Test that form_data_key is properly extracted from URL."""
-        mock_create_form_data.return_value = "extracted_form_key_xyz"
+        """Test that permalink_key is properly extracted from the durable URL."""
+        mock_create_permalink.return_value = "extracted_permalink_xyz"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         config = TableChartConfig(
@@ -749,19 +775,19 @@ class TestGenerateExploreLink:
             )
 
             assert result.data["error"] is None
-            assert result.data["form_data_key"] == "extracted_form_key_xyz"
-            assert "form_data_key=extracted_form_key_xyz" in result.data["url"]
+            assert result.data["permalink_key"] == "extracted_permalink_xyz"
+            assert result.data["form_data_key"] is None
+            assert "extracted_permalink_xyz" in result.data["url"]
+            assert result.data["url"] == (
+                "http://localhost:9001/explore/p/extracted_permalink_xyz/"
+            )
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_generate_explore_link_returns_form_data(
-        self, mock_create_form_data, mock_find_dataset, mcp_server
+        self, mock_find_dataset, mcp_server
     ):
         """Test that form_data dict is returned for external rendering."""
-        mock_create_form_data.return_value = "form_data_test_key"
         mock_find_dataset.return_value = _mock_dataset(id=1)
 
         config = XYChartConfig(
@@ -806,6 +832,7 @@ class TestGenerateExploreLink:
             assert result.data["url"] == ""
             assert result.data["form_data"] == {}
             assert result.data["form_data_key"] is None
+            assert result.data["permalink_key"] is None
             assert result.data["chart_type_label"] is None
             assert "Dataset not found: 99999" in result.data["error"]
             assert "list_datasets" in result.data["error"]
@@ -833,6 +860,7 @@ class TestGenerateExploreLink:
             )
             assert result.data["form_data"] == {}
             assert result.data["form_data_key"] is None
+            assert result.data["permalink_key"] is None
             assert result.data["chart_type_label"] is None
 
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
@@ -853,6 +881,7 @@ class TestGenerateExploreLink:
             assert result.data["url"] == ""
             assert result.data["form_data"] == {}
             assert result.data["form_data_key"] is None
+            assert result.data["permalink_key"] is None
             assert result.data["chart_type_label"] is None
             assert "Dataset not found: 99999" in result.data["error"]
 
@@ -879,6 +908,7 @@ class TestGenerateExploreLink:
             assert result.data["url"] == ""
             assert result.data["form_data"] == {}
             assert result.data["form_data_key"] is None
+            assert result.data["permalink_key"] is None
             assert result.data["chart_type_label"] is None
             assert "Dataset not found" in result.data["error"]
 
@@ -895,19 +925,14 @@ class TestGenerateExploreLinkColumnNormalization:
         "superset.mcp_service.chart.validation.dataset_validator.DatasetValidator._get_dataset_context"
     )
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_xy_chart_x_axis_normalized_in_form_data(
         self,
-        mock_create_form_data,
         mock_find_dataset,
         mock_get_context,
         mcp_server,
     ):
         """x-axis column name in wrong case is normalized in form_data."""
-        mock_create_form_data.return_value = "norm_test_key_1"
         mock_find_dataset.return_value = _mock_dataset(id=18)
         mock_get_context.return_value = DatasetContext(
             id=18,
@@ -942,19 +967,14 @@ class TestGenerateExploreLinkColumnNormalization:
         "superset.mcp_service.chart.validation.dataset_validator.DatasetValidator._get_dataset_context"
     )
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_filter_column_normalized_in_form_data(
         self,
-        mock_create_form_data,
         mock_find_dataset,
         mock_get_context,
         mcp_server,
     ):
         """Filter column name in wrong case is normalized in adhoc_filters."""
-        mock_create_form_data.return_value = "norm_test_key_2"
         mock_find_dataset.return_value = _mock_dataset(id=18)
         mock_get_context.return_value = DatasetContext(
             id=18,
@@ -1001,19 +1021,14 @@ class TestGenerateExploreLinkColumnNormalization:
         "superset.mcp_service.chart.validation.dataset_validator.DatasetValidator._get_dataset_context"
     )
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_normalization_fallback_when_dataset_not_found(
         self,
-        mock_create_form_data,
         mock_find_dataset,
         mock_get_context,
         mcp_server,
     ):
         """When dataset context is unavailable, original names pass through."""
-        mock_create_form_data.return_value = "norm_test_key_3"
         mock_find_dataset.return_value = _mock_dataset(id=99)
         mock_get_context.return_value = None
 
@@ -1046,21 +1061,19 @@ class TestGenerateExploreLinkValidation:
         """
         return
 
+    @patch(_PERMALINK_PATCH)
     @patch.object(generate_explore_link_module, "validate_and_compile")
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_validation_failure_returns_structured_error(
         self,
-        mock_create_form_data,
         mock_find_dataset,
         mock_validate,
+        mock_create_permalink,
         mcp_server,
     ):
         """Non-existent column → structured ChartGenerationError with suggestions,
-        and MCPCreateFormDataCommand must NOT be called (no cache write)."""
+        and CreateExplorePermalinkCommand must NOT be called (no cache write)."""
         from superset.mcp_service.chart.compile import CompileResult
         from superset.mcp_service.common.error_schemas import ChartGenerationError
 
@@ -1094,29 +1107,28 @@ class TestGenerateExploreLinkValidation:
 
             assert result.data["url"] == ""
             assert result.data["form_data_key"] is None
+            assert result.data["permalink_key"] is None
             assert result.data["chart_type_label"] is None
             error = result.data["error"]
             assert isinstance(error, dict)
             assert error["error_code"] == "CHART_VALIDATION_FAILED"
             assert "sum_boys" in error["suggestions"]
-            mock_create_form_data.assert_not_called()
+            mock_create_permalink.assert_not_called()
 
+    @patch(_PERMALINK_PATCH)
     @patch.object(
         generate_explore_link_module, "has_dataset_access", return_value=False
     )
     @patch("superset.daos.dataset.DatasetDAO.find_by_id")
-    @patch(
-        "superset.mcp_service.commands.create_form_data.MCPCreateFormDataCommand.run"
-    )
     @pytest.mark.asyncio
     async def test_dataset_access_denied_short_circuits(
         self,
-        mock_create_form_data,
         mock_find_dataset,
         unused_access_mock,
+        mock_create_permalink,
         mcp_server,
     ):
-        """has_dataset_access=False blocks the tool before any cache write."""
+        """has_dataset_access=False blocks the tool before any permalink write."""
         mock_find_dataset.return_value = _mock_dataset(id=3)
 
         config = TableChartConfig(
@@ -1133,4 +1145,4 @@ class TestGenerateExploreLinkValidation:
             assert result.data["chart_type_label"] is None
             # Surface as "not found" rather than leaking that the dataset exists.
             assert "Dataset not found" in result.data["error"]
-            mock_create_form_data.assert_not_called()
+            mock_create_permalink.assert_not_called()