From a0ef573f5ad2d9a86b4746e82f3196adeb318739 Mon Sep 17 00:00:00 2001
From: bobbyiliev <bobby@bobbyiliev.com>
Date: Wed, 10 Jun 2026 11:55:10 +0300
Subject: [PATCH] docs/mcp: document developer query tool

---
 .../mcp-server/mcp-developer-config.md        |  1 +
 .../mcp-server/mcp-developer-tools.md         | 40 ++++++++++++++++++-
 .../integrations/mcp-server/mcp-developer.md  |  9 +++--
 3 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/doc/user/content/integrations/mcp-server/mcp-developer-config.md b/doc/user/content/integrations/mcp-server/mcp-developer-config.md
index a178029460076..fbdd9d40ee4af 100644
--- a/doc/user/content/integrations/mcp-server/mcp-developer-config.md
+++ b/doc/user/content/integrations/mcp-server/mcp-developer-config.md
@@ -18,6 +18,7 @@ endpoint:
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `enable_mcp_developer` | `true` | Enable or disable the `/api/mcp/developer` endpoint. When the endpoint is disabled, requests return HTTP 503 (Service Unavailable). |
+| `enable_mcp_developer_query_tool` | `true` | Enable or disable the `query` tool on the developer endpoint. When disabled, the tool is hidden from `tools/list` and calls return an error. `query_system_catalog` remains available. |
 | `mcp_max_response_size` | `1000000` | Maximum response size in bytes. Queries exceeding this limit return an error. |
 
 ## Disabling the endpoint
diff --git a/doc/user/content/integrations/mcp-server/mcp-developer-tools.md b/doc/user/content/integrations/mcp-server/mcp-developer-tools.md
index 93573b6336ea4..61a666963be9f 100644
--- a/doc/user/content/integrations/mcp-server/mcp-developer-tools.md
+++ b/doc/user/content/integrations/mcp-server/mcp-developer-tools.md
@@ -14,7 +14,8 @@ menu:
 ### `query_system_catalog`
 
 Execute a read-only SQL query restricted to system catalog tables (`mz_*`,
-`pg_catalog`, `information_schema`).
+`pg_catalog`, `information_schema`). No cluster argument; prefer this for
+catalog lookups that do not need a cluster to run on.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -41,6 +42,43 @@ Only one statement per call is allowed. Write operations (`INSERT`, `UPDATE`,
 }
 ```
 
+### `query`
+
+Execute a read-only SQL query (`SELECT`, `SHOW`, or `EXPLAIN`) against any
+object the role can access, including system catalog and user objects. A
+cluster is required, which is what enables `EXPLAIN ANALYZE` and queries
+against indexed user objects.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cluster` | string | Yes | Exact cluster name the query should run on. |
+| `sql_query` | string | Yes | `SELECT`, `SHOW`, or `EXPLAIN` statement. |
+
+Only one statement per call is allowed. Write operations (`INSERT`, `UPDATE`,
+`CREATE`, etc.) are rejected. The tool is hidden when the operator has
+disabled it via [`enable_mcp_developer_query_tool`](/integrations/mcp-server/mcp-developer-config/).
+
+For pure system catalog lookups that do not need a cluster, prefer
+[`query_system_catalog`](#query_system_catalog).
+
+**Example response:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "[\n  [\n    \"Explained Query (fast path):\\n  →Constant (1 rows)\\n\\nTarget cluster: quickstart\\n\"\n  ]\n]"
+      }
+    ],
+    "isError": false
+  }
+}
+```
+
 ### Key system catalog tables
 
 | Scenario | Tables |
diff --git a/doc/user/content/integrations/mcp-server/mcp-developer.md b/doc/user/content/integrations/mcp-server/mcp-developer.md
index 9a2aa3172d1c3..78dfe93a9e022 100644
--- a/doc/user/content/integrations/mcp-server/mcp-developer.md
+++ b/doc/user/content/integrations/mcp-server/mcp-developer.md
@@ -266,9 +266,12 @@ Once connected to the MCP server, you can ask natural language questions like:
 | **What can I optimize to save costs?** | Queries the index advisor for materialized views that can be dematerialized and indexes that can be dropped. |
 
 The agent translates natural language questions into the appropriate system
-catalog queries, uses the [`query_system_catalog`
-tool](/integrations/mcp-server/mcp-developer-tools/#query_system_catalog) to run
-those queries, and synthesizes the results.
+catalog queries and runs them via either the
+[`query_system_catalog`](/integrations/mcp-server/mcp-developer-tools/#query_system_catalog)
+tool (catalog lookups with no cluster needed) or the
+[`query`](/integrations/mcp-server/mcp-developer-tools/#query) tool
+(`EXPLAIN ANALYZE` and read-only queries against user objects, both of which
+require a cluster), then synthesizes the results.
 
 ## Privileges