From cf7b0d8e4002a395d8d8937e1fc836baf848b25f Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Sun, 11 Oct 2026 17:36:36 -0700
Subject: [PATCH 1/5] fix(mcp): stop clickstack_sql callers guessing table and
timestamp names
Agents writing raw SQL had no tool that named a source's table, and the sql
examples hard-coded otel_logs and TimestampTime. Unqualified otel_logs only
resolves when tables sit in the connection's default database, and the seed
otel_logs schema has no TimestampTime, so the examples fail on most schemas.
- clickstack_list_sources returns each source's database-qualified table,
and the database for metric sources.
- The sql examples use
and placeholders.
- Unknown-table errors hint at clickstack_list_sources.
---
.changeset/mcp-sql-table-names.md | 9 +++
packages/api/src/mcp/__tests__/query.test.ts | 16 +++++
.../src/mcp/__tests__/queryTool.int.test.ts | 63 +++++++++++++++++++
.../api/src/mcp/__tests__/sources.int.test.ts | 28 +++++++++
packages/api/src/mcp/tools/query/helpers.ts | 13 ++++
packages/api/src/mcp/tools/query/sql.ts | 13 ++--
.../api/src/mcp/tools/sources/listSources.ts | 9 +++
7 files changed, 146 insertions(+), 5 deletions(-)
create mode 100644 .changeset/mcp-sql-table-names.md
diff --git a/.changeset/mcp-sql-table-names.md b/.changeset/mcp-sql-table-names.md
new file mode 100644
index 0000000000..674d945a24
--- /dev/null
+++ b/.changeset/mcp-sql-table-names.md
@@ -0,0 +1,9 @@
+---
+'@hyperdx/api': patch
+---
+
+fix(mcp): stop `clickstack_sql` callers from guessing table and timestamp column
+names. `clickstack_list_sources` now returns each source's database-qualified
+`table` (and `database` for metric sources), the `sql` examples use ``
+and `` placeholders instead of `otel_logs` and `TimestampTime`,
+and unknown-table errors point at `clickstack_list_sources`.
diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts
index 585ea7551f..3387fef684 100644
--- a/packages/api/src/mcp/__tests__/query.test.ts
+++ b/packages/api/src/mcp/__tests__/query.test.ts
@@ -229,6 +229,22 @@ describe('errorHint', () => {
expect(hint).toBeNull();
});
+ it.each([
+ "Unknown table expression identifier 'otel_logs' in scope SELECT count() FROM otel_logs",
+ 'Table default.otel_traces does not exist.',
+ 'Database o11y does not exist.',
+ ])('points unknown-table errors at clickstack_list_sources: %s', msg => {
+ expect(errorHint(msg)).toContain('clickstack_list_sources');
+ });
+
+ it('keeps pointing unknown-column errors at clickstack_describe_source', () => {
+ const hint = errorHint(
+ 'Unknown expression or function identifier `TimestampTime` in scope SELECT TimestampTime FROM t',
+ );
+ expect(hint).toContain('clickstack_describe_source');
+ expect(hint).not.toContain('clickstack_list_sources');
+ });
+
it('should NOT match lowercase "as" in cast expressions', () => {
const hint = errorHint(
'Syntax error: cannot cast as Float64 near token...',
diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
index 60bd0352d3..63c73d8d7f 100644
--- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts
+++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
@@ -813,6 +813,51 @@ describe('MCP Query Tools', () => {
},
);
+ describe('sql parameter examples', () => {
+ const getExamples = async () => {
+ const { tools } = await client.listTools();
+ const sqlParam = tools.find(t => t.name === 'clickstack_sql')!
+ .inputSchema.properties?.sql as { description: string };
+ return [
+ ...sqlParam.description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm),
+ ].map(match => match[1]);
+ };
+
+ // Agents copy examples literally. A concrete table or column in one
+ // becomes the guess, and it only exists on some schemas.
+ it('leave the table and timestamp column as placeholders', async () => {
+ const examples = await getExamples();
+
+ expect(examples).toHaveLength(2);
+ for (const sql of examples) {
+ expect(sql).toContain('FROM ');
+ expect(sql).toContain('');
+ expect(sql).not.toMatch(/otel_|TimestampTime/);
+ }
+ });
+
+ it('run once the placeholders are filled from a source', async () => {
+ const examples = await getExamples();
+
+ expect(examples).toHaveLength(2);
+ for (const example of examples) {
+ const sql = example
+ .replaceAll('', `${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`)
+ .replaceAll('', 'Timestamp');
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sql,
+ startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+ endTime: new Date().toISOString(),
+ });
+ expect({
+ sql,
+ error: result.isError ? getFirstText(result) : null,
+ }).toEqual({ sql, error: null });
+ }
+ });
+ });
+
it('returns plain query rows unchanged', async () => {
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
@@ -865,6 +910,24 @@ describe('MCP Query Tools', () => {
/UNKNOWN_TABLE|doesn.t exist|unknown/i,
);
});
+
+ it.each([
+ 'nonexistent_table_xyz',
+ `${DEFAULT_DATABASE}.nonexistent_table_xyz`,
+ ])(
+ 'hints that %s should come from clickstack_list_sources',
+ async table => {
+ const result = await callTool(client, 'clickstack_sql', {
+ connectionId: connection._id.toString(),
+ sql: `SELECT 1 FROM ${table} LIMIT 1`,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toContain(
+ 'HINT: Use the `table` of a source from clickstack_list_sources',
+ );
+ },
+ );
});
describe('clickstack_table errors', () => {
diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts
index 7e86e7c3a5..e56e51f259 100644
--- a/packages/api/src/mcp/__tests__/sources.int.test.ts
+++ b/packages/api/src/mcp/__tests__/sources.int.test.ts
@@ -140,6 +140,21 @@ describe('MCP Source Tools', () => {
expect(output.nextStep).toContain('clickstack_describe_source');
});
+ // clickstack_sql callers need this for FROM. Without it they guess
+ // otel_logs, which only resolves when the tables sit in the
+ // connection's default database.
+ it('includes the database-qualified table each log and trace source reads', async () => {
+ const result = await callTool(client, 'clickstack_list_sources');
+ const output = JSON.parse(getFirstText(result));
+
+ const trace = output.sources.find(
+ (s: any) => s.kind === SourceKind.Trace,
+ );
+ const log = output.sources.find((s: any) => s.kind === SourceKind.Log);
+ expect(trace.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_TRACES_TABLE}`);
+ expect(log.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`);
+ });
+
it('should include keyColumns from source config without ClickHouse queries', async () => {
const result = await callTool(client, 'clickstack_list_sources');
const output = JSON.parse(getFirstText(result));
@@ -248,6 +263,19 @@ describe('MCP Source Tools', () => {
expect(output.metricsUsage).toContain('metricType + metricName');
});
+ it('includes the database its metricTables live in', async () => {
+ const metricSource = await createMetricSource();
+
+ const result = await callTool(client, 'clickstack_list_sources');
+ const output = JSON.parse(getFirstText(result));
+
+ const metric = output.sources.find(
+ (s: any) => s.id === metricSource._id.toString(),
+ );
+ expect(metric.database).toBe(DEFAULT_DATABASE);
+ expect(metric.table).toBeUndefined();
+ });
+
it('falls back to a wider lookback when no metrics reported in the last 24h', async () => {
const metricSource = await createMetricSource('Sparse Metrics');
const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000);
diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts
index 708b96c0f7..9991858556 100644
--- a/packages/api/src/mcp/tools/query/helpers.ts
+++ b/packages/api/src/mcp/tools/query/helpers.ts
@@ -954,6 +954,19 @@ export function errorHint(msg: string, error?: unknown): string | null {
'Add a LIMIT, narrow the time range, or add filters to reduce the result set.'
);
}
+ // Checked before unknown identifiers: "Unknown table expression identifier"
+ // names a table, so describe_source's column list would not help.
+ if (
+ /Unknown table expression identifier|(Table|Database) \S+ does not exist|UNKNOWN_(TABLE|DATABASE)/.test(
+ msg,
+ )
+ ) {
+ return (
+ 'Use the `table` of a source from clickstack_list_sources, which is ' +
+ 'qualified with its database. Unqualified names resolve only in the ' +
+ "connection's default database."
+ );
+ }
if (
/Unknown (expression|identifier)|UNKNOWN_IDENTIFIER|Missing columns/i.test(
msg,
diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts
index eb12492222..eba36245ff 100644
--- a/packages/api/src/mcp/tools/query/sql.ts
+++ b/packages/api/src/mcp/tools/query/sql.ts
@@ -39,13 +39,16 @@ const sqlSchema = z.object({
' $__interval_s — raw interval in seconds\n' +
' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' +
' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' +
+ "In the examples, replace with a source's `table` and " +
+ 'with its `timestampColumn`, both from clickstack_list_sources. Table and column ' +
+ 'names differ between sources, so do not guess them.\n\n' +
'Example (time-series):\n' +
- ' SELECT $__timeInterval(TimestampTime) AS ts, ServiceName, count() ' +
- 'FROM otel_logs WHERE $__timeFilter(TimestampTime) GROUP BY ServiceName, ts ORDER BY ts\n\n' +
+ ' SELECT $__timeInterval() AS ts, ServiceName, count() ' +
+ 'FROM WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' +
'Example (table):\n' +
- ' SELECT ServiceName, count() AS n FROM otel_logs ' +
- 'WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' +
- 'AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) ' +
+ ' SELECT ServiceName, count() AS n FROM ' +
+ 'WHERE >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' +
+ 'AND < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) ' +
'GROUP BY ServiceName ORDER BY n DESC LIMIT 20',
),
startTime: startTimeSchema,
diff --git a/packages/api/src/mcp/tools/sources/listSources.ts b/packages/api/src/mcp/tools/sources/listSources.ts
index b7ce2beac9..e3deed4167 100644
--- a/packages/api/src/mcp/tools/sources/listSources.ts
+++ b/packages/api/src/mcp/tools/sources/listSources.ts
@@ -244,6 +244,15 @@ export function registerListSources({
timestampColumn: s.timestampValueExpression,
};
+ // For clickstack_sql's FROM. An unqualified name only resolves in the
+ // connection's default database. Metric sources keep one table per
+ // kind in metricTables, so they get the database to qualify them with.
+ if (s.from.tableName) {
+ meta.table = `${s.from.databaseName}.${s.from.tableName}`;
+ } else {
+ meta.database = s.from.databaseName;
+ }
+
if (s.section) {
meta.section = s.section;
}
From 1c68142ed78196b913dbd5794c3473b8e70f832d Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:11:03 -0700
Subject: [PATCH 2/5] test(mcp): read the sql param description without a type
assertion
The cast tripped no-unsafe-type-assertion and took the api package one
warning over the CI lint ceiling.
---
packages/api/src/mcp/__tests__/queryTool.int.test.ts | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
index 63c73d8d7f..3bcc454cc4 100644
--- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts
+++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
@@ -817,10 +817,14 @@ describe('MCP Query Tools', () => {
const getExamples = async () => {
const { tools } = await client.listTools();
const sqlParam = tools.find(t => t.name === 'clickstack_sql')!
- .inputSchema.properties?.sql as { description: string };
- return [
- ...sqlParam.description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm),
- ].map(match => match[1]);
+ .inputSchema.properties?.sql;
+ const description =
+ sqlParam && typeof sqlParam === 'object' && 'description' in sqlParam
+ ? String(sqlParam.description)
+ : '';
+ return [...description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm)].map(
+ match => match[1],
+ );
};
// Agents copy examples literally. A concrete table or column in one
From 5fb24777d21c1fc705e493c77603b3a077331692 Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:22:21 -0700
Subject: [PATCH 3/5] fix(mcp): quote list_sources table names and give every
metric source its database
Agents paste table into FROM, so a database like observability-prod
broke the query. Metric sources that also set from.tableName got a table
instead of the database their metricTables live in.
---
.../api/src/mcp/__tests__/sources.int.test.ts | 47 +++++++++++++++++++
.../api/src/mcp/tools/sources/listSources.ts | 14 +++---
2 files changed, 55 insertions(+), 6 deletions(-)
diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts
index e56e51f259..59367443b3 100644
--- a/packages/api/src/mcp/__tests__/sources.int.test.ts
+++ b/packages/api/src/mcp/__tests__/sources.int.test.ts
@@ -155,6 +155,25 @@ describe('MCP Source Tools', () => {
expect(log.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`);
});
+ it('quotes table parts that are not bare identifiers so FROM still parses', async () => {
+ const source = await Source.create({
+ kind: SourceKind.Log,
+ team: team._id,
+ from: { databaseName: 'observability-prod', tableName: 'otel.logs' },
+ timestampValueExpression: 'Timestamp',
+ connection: connection._id,
+ name: 'Quoted logs',
+ });
+
+ const result = await callTool(client, 'clickstack_list_sources');
+ const output = JSON.parse(getFirstText(result));
+
+ const log = output.sources.find(
+ (s: any) => s.id === source._id.toString(),
+ );
+ expect(log.table).toBe('`observability-prod`.`otel.logs`');
+ });
+
it('should include keyColumns from source config without ClickHouse queries', async () => {
const result = await callTool(client, 'clickstack_list_sources');
const output = JSON.parse(getFirstText(result));
@@ -276,6 +295,34 @@ describe('MCP Source Tools', () => {
expect(metric.table).toBeUndefined();
});
+ // Metric sources may also set from.tableName, but their queryable
+ // tables are still the ones in metricTables.
+ it('includes the database for a metric source that also names a table', async () => {
+ const metricSource = await Source.create({
+ kind: SourceKind.Metric,
+ team: team._id,
+ from: {
+ databaseName: DEFAULT_DATABASE,
+ tableName: 'otel_metrics_gauge',
+ },
+ metricTables: {
+ [MetricsDataType.Gauge.toLowerCase()]: 'otel_metrics_gauge',
+ },
+ timestampValueExpression: 'TimeUnix',
+ connection: connection._id,
+ name: 'Named metrics',
+ });
+
+ const result = await callTool(client, 'clickstack_list_sources');
+ const output = JSON.parse(getFirstText(result));
+
+ const metric = output.sources.find(
+ (s: any) => s.id === metricSource._id.toString(),
+ );
+ expect(metric.database).toBe(DEFAULT_DATABASE);
+ expect(metric.table).toBeUndefined();
+ });
+
it('falls back to a wider lookback when no metrics reported in the last 24h', async () => {
const metricSource = await createMetricSource('Sparse Metrics');
const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000);
diff --git a/packages/api/src/mcp/tools/sources/listSources.ts b/packages/api/src/mcp/tools/sources/listSources.ts
index e3deed4167..48cc7a3106 100644
--- a/packages/api/src/mcp/tools/sources/listSources.ts
+++ b/packages/api/src/mcp/tools/sources/listSources.ts
@@ -7,6 +7,7 @@ import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
import {
Metadata,
MetadataCache,
+ quoteIdentifierIfNeeded,
} from '@hyperdx/common-utils/dist/core/metadata';
import { SourceKind } from '@hyperdx/common-utils/dist/types';
import { z } from 'zod';
@@ -244,13 +245,14 @@ export function registerListSources({
timestampColumn: s.timestampValueExpression,
};
- // For clickstack_sql's FROM. An unqualified name only resolves in the
- // connection's default database. Metric sources keep one table per
- // kind in metricTables, so they get the database to qualify them with.
- if (s.from.tableName) {
- meta.table = `${s.from.databaseName}.${s.from.tableName}`;
+ // For clickstack_sql's FROM, so each part is quoted when it needs to
+ // be. An unqualified name only resolves in the connection's default
+ // database. Metric sources query the tables in metricTables, even
+ // when from.tableName is set, so they get the database instead.
+ if (s.kind !== SourceKind.Metric && s.from.tableName) {
+ meta.table = `${quoteIdentifierIfNeeded(s.from.databaseName)}.${quoteIdentifierIfNeeded(s.from.tableName)}`;
} else {
- meta.database = s.from.databaseName;
+ meta.database = quoteIdentifierIfNeeded(s.from.databaseName);
}
if (s.section) {
From cc07b202e0728ac404db13a036cc7387b857654f Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:22:26 -0700
Subject: [PATCH 4/5] fix(mcp): give the unknown-table hint only to raw SQL and
fix placeholder guidance
Source-based tools were sent back to clickstack_list_sources, which hands
back the same table that just failed. The sql examples now say to use the
first timestampColumn expression and how to qualify metric tables.
---
packages/api/src/mcp/__tests__/query.test.ts | 24 ++++++--
.../src/mcp/__tests__/queryTool.int.test.ts | 55 ++++++++++++++++---
packages/api/src/mcp/tools/query/helpers.ts | 21 ++++---
packages/api/src/mcp/tools/query/sql.ts | 6 +-
4 files changed, 85 insertions(+), 21 deletions(-)
diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts
index 3387fef684..0855c40bc7 100644
--- a/packages/api/src/mcp/__tests__/query.test.ts
+++ b/packages/api/src/mcp/__tests__/query.test.ts
@@ -229,13 +229,29 @@ describe('errorHint', () => {
expect(hint).toBeNull();
});
- it.each([
+ const unknownTableErrors = [
"Unknown table expression identifier 'otel_logs' in scope SELECT count() FROM otel_logs",
'Table default.otel_traces does not exist.',
'Database o11y does not exist.',
- ])('points unknown-table errors at clickstack_list_sources: %s', msg => {
- expect(errorHint(msg)).toContain('clickstack_list_sources');
- });
+ ];
+
+ it.each(unknownTableErrors)(
+ 'points unknown-table errors in raw SQL at clickstack_list_sources: %s',
+ msg => {
+ expect(errorHint(msg, undefined, { rawSql: true })).toContain(
+ 'clickstack_list_sources',
+ );
+ },
+ );
+
+ // Source-based tools take a sourceId, so the failing table is the source's
+ // own and listing sources would only hand it back.
+ it.each(unknownTableErrors)(
+ 'does not point source-based tools at clickstack_list_sources: %s',
+ msg => {
+ expect(errorHint(msg) ?? '').not.toContain('clickstack_list_sources');
+ },
+ );
it('keeps pointing unknown-column errors at clickstack_describe_source', () => {
const hint = errorHint(
diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
index 3bcc454cc4..c6543a23c3 100644
--- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts
+++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts
@@ -814,18 +814,32 @@ describe('MCP Query Tools', () => {
);
describe('sql parameter examples', () => {
- const getExamples = async () => {
+ const getDescription = async () => {
const { tools } = await client.listTools();
const sqlParam = tools.find(t => t.name === 'clickstack_sql')!
.inputSchema.properties?.sql;
- const description =
- sqlParam && typeof sqlParam === 'object' && 'description' in sqlParam
- ? String(sqlParam.description)
- : '';
- return [...description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm)].map(
- match => match[1],
- );
+ return sqlParam &&
+ typeof sqlParam === 'object' &&
+ 'description' in sqlParam
+ ? String(sqlParam.description)
+ : '';
};
+ const getExamples = async () =>
+ [
+ ...(await getDescription()).matchAll(/^Example \(.+\):\n {2}(.+)$/gm),
+ ].map(match => match[1]);
+
+ // timestampColumn can list several columns ("TimestampTime, Timestamp"),
+ // which breaks $__timeFilter if pasted whole. Metric sources return a
+ // database instead of a table.
+ it('say how to fill placeholders for multi-column timestamps and metric sources', async () => {
+ const description = await getDescription();
+
+ expect(description).toMatch(
+ /first expression in its `timestampColumn`/,
+ );
+ expect(description).toMatch(/metricTables.*`database`/);
+ });
// Agents copy examples literally. A concrete table or column in one
// becomes the guess, and it only exists on some schemas.
@@ -946,6 +960,31 @@ describe('MCP Query Tools', () => {
/UNKNOWN_IDENTIFIER|Missing columns|unknown/i,
);
});
+
+ it('does not send a source whose table is missing back to clickstack_list_sources', async () => {
+ const missing = await Source.create({
+ kind: SourceKind.Log,
+ team: team._id,
+ from: {
+ databaseName: DEFAULT_DATABASE,
+ tableName: 'nonexistent_table_xyz',
+ },
+ timestampValueExpression: 'Timestamp',
+ connection: connection._id,
+ name: 'Missing logs',
+ });
+
+ const result = await callTool(client, 'clickstack_table', {
+ sourceId: missing._id.toString(),
+ select: [{ aggFn: 'count' }],
+ });
+
+ expect(result.isError).toBe(true);
+ expect(getFirstText(result)).toMatch(
+ /UNKNOWN_TABLE|does(n.t| not) exist/i,
+ );
+ expect(getFirstText(result)).not.toContain('clickstack_list_sources');
+ });
});
describe('clickstack_timeseries errors', () => {
diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts
index 9991858556..fd1b734d40 100644
--- a/packages/api/src/mcp/tools/query/helpers.ts
+++ b/packages/api/src/mcp/tools/query/helpers.ts
@@ -684,7 +684,7 @@ export async function runConfigTile(
});
return formatQueryResult(result);
} catch (e) {
- return clickHouseErrorResult(e);
+ return clickHouseErrorResult(e, { rawSql: true });
}
}
@@ -841,11 +841,11 @@ function hasNodeErrorCode(val: unknown, codes: ReadonlySet): boolean {
*/
export function clickHouseErrorResult(
e: unknown,
- context?: string | { prefix?: string; suffix?: string },
+ context?: string | { prefix?: string; suffix?: string; rawSql?: boolean },
): McpErrorResult {
- const { prefix, suffix } =
+ const { prefix, suffix, rawSql } =
typeof context === 'string'
- ? { prefix: context, suffix: undefined }
+ ? { prefix: context, suffix: undefined, rawSql: undefined }
: (context ?? {});
// Prefer .message, but fall back to .cause.message when the wrapper
@@ -857,7 +857,7 @@ export function clickHouseErrorResult(
(e.cause instanceof Error ? e.cause.message : '') ||
String(e)
: String(e);
- const hint = errorHint(raw, e);
+ const hint = errorHint(raw, e, { rawSql });
const base = hint ? `${raw}\n\nHINT: ${hint}` : raw;
const text = `${prefix ? `${prefix}: ` : ''}${base}${suffix ? ` ${suffix}` : ''}`;
@@ -897,7 +897,11 @@ export function isQueryOutOfTime(e: unknown): boolean {
}
/** @internal Exported for testing only. */
-export function errorHint(msg: string, error?: unknown): string | null {
+export function errorHint(
+ msg: string,
+ error?: unknown,
+ options?: { rawSql?: boolean },
+): string | null {
const unknownVariableError = findCause(
error,
(e): e is UnknownVariableError => e instanceof UnknownVariableError,
@@ -955,8 +959,11 @@ export function errorHint(msg: string, error?: unknown): string | null {
);
}
// Checked before unknown identifiers: "Unknown table expression identifier"
- // names a table, so describe_source's column list would not help.
+ // names a table, so describe_source's column list would not help. Only raw
+ // SQL names its own table; source-based tools would be sent back to the
+ // same source table that just failed.
if (
+ options?.rawSql &&
/Unknown table expression identifier|(Table|Database) \S+ does not exist|UNKNOWN_(TABLE|DATABASE)/.test(
msg,
)
diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts
index eba36245ff..14affcdc22 100644
--- a/packages/api/src/mcp/tools/query/sql.ts
+++ b/packages/api/src/mcp/tools/query/sql.ts
@@ -40,8 +40,10 @@ const sqlSchema = z.object({
' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' +
' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' +
"In the examples, replace with a source's `table` and " +
- 'with its `timestampColumn`, both from clickstack_list_sources. Table and column ' +
- 'names differ between sources, so do not guess them.\n\n' +
+ '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' +
' SELECT $__timeInterval() AS ts, ServiceName, count() ' +
'FROM WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' +
From faf11efebada4adf86a370afec5d67b02c674301 Mon Sep 17 00:00:00 2001
From: George Goldenberg <228832143+squaredg@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:22:44 -0700
Subject: [PATCH 5/5] chore: scope the changeset's unknown-table hint to
clickstack_sql
---
.changeset/mcp-sql-table-names.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.changeset/mcp-sql-table-names.md b/.changeset/mcp-sql-table-names.md
index 674d945a24..110346f367 100644
--- a/.changeset/mcp-sql-table-names.md
+++ b/.changeset/mcp-sql-table-names.md
@@ -6,4 +6,4 @@ fix(mcp): stop `clickstack_sql` callers from guessing table and timestamp column
names. `clickstack_list_sources` now returns each source's database-qualified
`table` (and `database` for metric sources), the `sql` examples use ``
and `` placeholders instead of `otel_logs` and `TimestampTime`,
-and unknown-table errors point at `clickstack_list_sources`.
+and unknown-table errors from `clickstack_sql` point at `clickstack_list_sources`.