From f514f284416eb7fd669437919eeb62c70fd86a75 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <alex.fedotyev@clickhouse.com>
Date: Tue, 5 May 2026 19:34:40 +0000
Subject: [PATCH 1/2] feat: add groupByColumnsOnLeft to MCP dashboard table
 tile schema

Surfaces the table-tile display option that PR #2149 added to the
external API to MCP clients. The conversion path already round-trips
the field; this advertises it on the MCP table tile schema and
extends the existing multi-tile MCP test to assert the value
survives save -> fetch.

Follow-up to #2149.
---
 .changeset/mcp-table-group-by-on-left.md          | 5 +++++
 packages/api/src/mcp/__tests__/dashboards.test.ts | 7 +++++++
 packages/api/src/mcp/tools/dashboards/schemas.ts  | 7 +++++++
 3 files changed, 19 insertions(+)
 create mode 100644 .changeset/mcp-table-group-by-on-left.md

diff --git a/.changeset/mcp-table-group-by-on-left.md b/.changeset/mcp-table-group-by-on-left.md
new file mode 100644
index 0000000000..e23073adaa
--- /dev/null
+++ b/.changeset/mcp-table-group-by-on-left.md
@@ -0,0 +1,5 @@
+---
+'@hyperdx/api': patch
+---
+
+Add groupByColumnsOnLeft to MCP dashboard table tile schema
diff --git a/packages/api/src/mcp/__tests__/dashboards.test.ts b/packages/api/src/mcp/__tests__/dashboards.test.ts
index 99d7bde30b..3e065d9a0a 100644
--- a/packages/api/src/mcp/__tests__/dashboards.test.ts
+++ b/packages/api/src/mcp/__tests__/dashboards.test.ts
@@ -351,6 +351,8 @@ describe('MCP Dashboard Tools', () => {
               displayType: 'table',
               sourceId,
               select: [{ aggFn: 'count' }],
+              groupBy: 'SpanName',
+              groupByColumnsOnLeft: true,
             },
           },
           {
@@ -392,6 +394,11 @@ describe('MCP Dashboard Tools', () => {
       expect(result.isError).toBeFalsy();
       const output = JSON.parse(getFirstText(result));
       expect(output.tiles).toHaveLength(5);
+
+      const tableTile = output.tiles.find(
+        (t: { name: string }) => t.name === 'Table',
+      );
+      expect(tableTile.config.groupByColumnsOnLeft).toBe(true);
     });
 
     it('should create a dashboard with a raw SQL tile', async () => {
diff --git a/packages/api/src/mcp/tools/dashboards/schemas.ts b/packages/api/src/mcp/tools/dashboards/schemas.ts
index b01f8c9454..b3aaffe044 100644
--- a/packages/api/src/mcp/tools/dashboards/schemas.ts
+++ b/packages/api/src/mcp/tools/dashboards/schemas.ts
@@ -146,6 +146,13 @@ const mcpTableTileSchema = mcpTileLayoutSchema.extend({
       ),
     orderBy: z.string().optional().describe('Sort results by this column'),
     asRatio: z.boolean().optional(),
+    groupByColumnsOnLeft: z
+      .boolean()
+      .optional()
+      .describe(
+        'Render Group By columns on the left side of the table, before the series columns. ' +
+          'Default false (Group By columns on the right).',
+      ),
   }),
 });
 

From 3de9c9a49a01f734d7b83416797f9673844208a9 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <alex.fedotyev@clickhouse.com>
Date: Tue, 5 May 2026 19:48:01 +0000
Subject: [PATCH 2/2] test: guard tableTile lookup with toBeDefined

---
 packages/api/src/mcp/__tests__/dashboards.test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/api/src/mcp/__tests__/dashboards.test.ts b/packages/api/src/mcp/__tests__/dashboards.test.ts
index 3e065d9a0a..f2a8eaf1be 100644
--- a/packages/api/src/mcp/__tests__/dashboards.test.ts
+++ b/packages/api/src/mcp/__tests__/dashboards.test.ts
@@ -398,6 +398,7 @@ describe('MCP Dashboard Tools', () => {
       const tableTile = output.tiles.find(
         (t: { name: string }) => t.name === 'Table',
       );
+      expect(tableTile).toBeDefined();
       expect(tableTile.config.groupByColumnsOnLeft).toBe(true);
     });