From 1731b9f71e95e3060f5ec56887d44d602f078787 Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Sun, 11 Oct 2026 17:46:30 -0700
Subject: [PATCH] feat(mcp): accept sourceId in clickstack_sql so
$__sourceTable resolves
clickstack_sql took only a connectionId, so agents had to write table names
themselves and guessed them. $__sourceTable already exists, and raw SQL
dashboard tiles resolve it through runConfigTile; the MCP tool just never
accepted a source.
Add an optional sourceId, passed to the tile. Reject a source that does not
exist or belongs to another team, a source whose connection differs from
connectionId, and $__sourceTable without a sourceId (the renderer's own
message says to select a source in the UI). The time-series example now
reads FROM $__sourceTable.
---
.changeset/mcp-sql-source-id.md | 8 ++
.../src/mcp/__tests__/queryTool.int.test.ts | 119 +++++++++++++++++-
packages/api/src/mcp/tools/query/sql.ts | 51 +++++++-
3 files changed, 171 insertions(+), 7 deletions(-)
create mode 100644 .changeset/mcp-sql-source-id.md
diff --git a/.changeset/mcp-sql-source-id.md b/.changeset/mcp-sql-source-id.md
new file mode 100644
index 0000000000..56fb54907a
--- /dev/null
+++ b/.changeset/mcp-sql-source-id.md
@@ -0,0 +1,8 @@
+---
+'@hyperdx/api': patch
+---
+
+feat(mcp): `clickstack_sql` accepts an optional `sourceId`, so `$__sourceTable`
+expands to that source's table. Unknown sources, other teams' sources, and a
+source on a different connection than `connectionId` are rejected, as is
+`$__sourceTable` without a `sourceId`.
diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
index c6543a23c3..c4926279e3 100644
--- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts
+++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
@@ -1,6 +1,7 @@
import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
import { MetricsDataType, SourceKind } from '@hyperdx/common-utils/dist/types';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ObjectId } from 'mongodb';
import * as config from '@/config';
import {
@@ -20,6 +21,7 @@ import {
import { McpContext } from '@/mcp/tools/types';
import Connection from '@/models/connection';
import { Source, type SourceDocument } from '@/models/source';
+import Team from '@/models/team';
import { callTool, createTestClient, getFirstText } from './mcpTestUtils';
@@ -163,6 +165,16 @@ describe('MCP Query Tools', () => {
expect(tool!.inputSchema.required).toContain('connectionId');
expect(tool!.inputSchema.required).toContain('sql');
});
+
+ it('exposes an optional sourceId on clickstack_sql', async () => {
+ const { tools } = await client.listTools();
+ const tool = tools.find(t => t.name === 'clickstack_sql')!;
+
+ expect(Object.keys(tool.inputSchema.properties ?? {})).toContain(
+ 'sourceId',
+ );
+ expect(tool.inputSchema.required).not.toContain('sourceId');
+ });
});
// ─── clickstack_timeseries ─────────────────────────────────────────────────────
@@ -848,12 +860,19 @@ describe('MCP Query Tools', () => {
expect(examples).toHaveLength(2);
for (const sql of examples) {
- expect(sql).toContain('FROM
');
+ expect(sql).toMatch(/FROM (|\$__sourceTable) /);
expect(sql).toContain('');
expect(sql).not.toMatch(/otel_|TimestampTime/);
}
});
+ it('show $__sourceTable for a source and for any other table', async () => {
+ const [timeSeries, table] = await getExamples();
+
+ expect(timeSeries).toContain('FROM $__sourceTable ');
+ expect(table).toContain('FROM ');
+ });
+
it('run once the placeholders are filled from a source', async () => {
const examples = await getExamples();
@@ -864,6 +883,7 @@ describe('MCP Query Tools', () => {
.replaceAll('', 'Timestamp');
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
+ sourceId: logSource._id.toString(),
sql,
startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
endTime: new Date().toISOString(),
@@ -876,6 +896,103 @@ describe('MCP Query Tools', () => {
});
});
+ describe('sourceId', () => {
+ const countSql =
+ 'SELECT count() AS n FROM $__sourceTable WHERE $__timeFilter(Timestamp)';
+
+ it('resolves $__sourceTable to the table of the given source', async () => {
+ const now = Date.now();
+ await bulkInsertLogs(
+ [1, 2, 3].map(minutesAgo => ({
+ Body: 'from source',
+ ServiceName: 'sql-source',
+ SeverityText: 'INFO',
+ Timestamp: new Date(now - minutesAgo * 60 * 1000),
+ })),
+ );
+
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sourceId: logSource._id.toString(),
+ sql: `${countSql} AND ServiceName = 'sql-source'`,
+ startTime: new Date(now - 60 * 60 * 1000).toISOString(),
+ endTime: new Date(now).toISOString(),
+ });
+
+ expect(result.isError).toBeFalsy();
+ expect(JSON.parse(getFirstText(result)).result.data).toEqual([
+ { n: '3' },
+ ]);
+ });
+
+ it('rejects $__sourceTable without a sourceId, saying to pass one', async () => {
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sql: countSql,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toContain(
+ '$__sourceTable needs a sourceId',
+ );
+ });
+
+ it('rejects a sourceId that does not exist', async () => {
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sourceId: new ObjectId().toString(),
+ sql: countSql,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toContain('Source not found');
+ });
+
+ it("rejects another team's sourceId as not found", async () => {
+ const otherTeam = await Team.create({ name: 'Other Team' });
+ const otherSource = await Source.create({
+ kind: SourceKind.Log,
+ team: otherTeam._id,
+ from: {
+ databaseName: DEFAULT_DATABASE,
+ tableName: DEFAULT_LOGS_TABLE,
+ },
+ timestampValueExpression: 'Timestamp',
+ connection: connection._id,
+ name: 'Other Logs',
+ });
+
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sourceId: otherSource._id.toString(),
+ sql: countSql,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toContain('Source not found');
+ });
+
+ // $__sourceTable would otherwise expand to a table on another server.
+ it('rejects a sourceId whose connection differs from connectionId', async () => {
+ const otherConnection = await Connection.create({
+ team: team._id,
+ name: 'Other',
+ host: config.CLICKHOUSE_HOST,
+ username: config.CLICKHOUSE_USER,
+ password: config.CLICKHOUSE_PASSWORD,
+ });
+
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: otherConnection._id.toString(),
+ sourceId: logSource._id.toString(),
+ sql: countSql,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toContain('does not match the connection');
+ });
+ });
+
it('returns plain query rows unchanged', async () => {
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts
index 14affcdc22..74e965e904 100644
--- a/packages/api/src/mcp/tools/query/sql.ts
+++ b/packages/api/src/mcp/tools/query/sql.ts
@@ -1,6 +1,8 @@
+import { hasMacro } from '@hyperdx/common-utils/dist/macros';
import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables';
import { z } from 'zod';
+import { getSource } from '@/controllers/sources';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
@@ -17,6 +19,14 @@ const sqlSchema = z.object({
'Connection ID (required). This is the only split tool that needs a connectionId ' +
'instead of sourceId. Call clickstack_list_sources to find available connections.',
),
+ sourceId: z
+ .string()
+ .optional()
+ .describe(
+ 'Source ID. Optional. Set it when the query reads a table backed by a source, so ' +
+ "`$__sourceTable` expands to that source's database.table. The source's " +
+ 'connection must match connectionId. Call clickstack_list_sources to find source IDs.',
+ ),
sql: z
.string()
.describe(
@@ -38,15 +48,17 @@ const sqlSchema = z.object({
' $__timeInterval_ms(column) — same with millisecond precision\n' +
' $__interval_s — raw interval in seconds\n' +
' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' +
+ " $__sourceTable — the source's database.table. Requires sourceId.\n" +
' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' +
"In the examples, replace with a source's `table` and " +
'with the first expression in its `timestampColumn`, both from ' +
- 'clickstack_list_sources. For a metric source, use a table from its ' +
- 'metricTables qualified with its `database`. Table and column names differ ' +
- 'between sources, so do not guess them.\n\n' +
- 'Example (time-series):\n' +
+ 'clickstack_list_sources, or pass that source as sourceId and use ' +
+ '$__sourceTable. For a metric source, use a table from its metricTables ' +
+ 'qualified with its `database`. Table and column names differ between ' +
+ 'sources, so do not guess them.\n\n' +
+ 'Example (time-series, with sourceId):\n' +
' SELECT $__timeInterval() AS ts, ServiceName, count() ' +
- 'FROM WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' +
+ 'FROM $__sourceTable WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' +
'Example (table):\n' +
' SELECT ServiceName, count() AS n FROM ' +
'WHERE >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' +
@@ -79,7 +91,8 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
'A single-table aggregation, top-N, time-series, or row browse is ALWAYS a ' +
'builder-tool job, never raw SQL. If you are unsure, try the builder tool first and only ' +
'fall back to SQL if it cannot express what you need.\n\n' +
- 'Requires connectionId (not sourceId) — call clickstack_list_sources to find connections. ' +
+ 'Requires connectionId — call clickstack_list_sources to find connections. Pass sourceId ' +
+ 'too when querying a source, so $__sourceTable resolves to its table. ' +
'Call clickstack_describe_source to discover column names before writing SQL.\n\n' +
'Results are always returned as table rows — for time-series semantics, ' +
'include a time column and ORDER BY it in your SQL.',
@@ -105,6 +118,31 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
);
}
+ if (input.sourceId) {
+ const source = await getSource(teamId.toString(), input.sourceId);
+ if (!source) {
+ return mcpUserError(
+ `Source not found: ${input.sourceId}. Call clickstack_list_sources to discover available source IDs.`,
+ );
+ }
+ // $__sourceTable expands to the source's table, so a mismatch would run
+ // the query against a table on another server.
+ const sourceConnectionId = source.connection.toString();
+ if (sourceConnectionId !== input.connectionId) {
+ return mcpUserError(
+ `connectionId "${input.connectionId}" does not match the connection of source ` +
+ `"${input.sourceId}" ("${sourceConnectionId}"). Use the source's own ` +
+ 'connection or drop sourceId from the call.',
+ );
+ }
+ } else if (hasMacro(input.sql, 'sourceTable')) {
+ return mcpUserError(
+ '$__sourceTable needs a sourceId to know which table to expand to. ' +
+ 'Pass the sourceId of a source from clickstack_list_sources, or write ' +
+ "the source's `table` in place of the macro.",
+ );
+ }
+
// Raw SQL only uses displayType to pick which query params to bind, and
// only time-series types bind the interval params this tool advertises
// ({intervalSeconds}, $__interval_s, $__timeInterval). Rows come back
@@ -113,6 +151,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
configType: 'sql' as const,
displayType: 'line' as const,
connectionId: input.connectionId,
+ sourceId: input.sourceId,
sqlTemplate: input.sql,
});