- Category: databases
- Auth: DCR_OAUTH
- Composio-managed OAuth available? No
- Tools: 32
- Triggers: 0
- Slug:
CLICKHOUSE_MCP - Version: 20261018_00
Tools
Clickstack delete dashboard
Clickstack delete dashboard
Clickstack delete source
Clickstack delete source
Clickstack delete webhook
Clickstack delete webhook
Clickstack describe metric
Clickstack describe metric
CLICKHOUSE_MCP_CLICKSTACK_DESCRIBE_METRICDRILL-DOWN: Use after clickstack_list_metrics (or after a clickstack_describe_source sample) to get attribute keys, sampled values, unit, and description for a specific (metricName, kind) pair. Attribute keys vary per metric — not per source — so always call this before clickstack_timeseries / clickstack_table for any metric you’ve never queried.REQUIRES kind — pass the gauge/sum/histogram/exponential histogram/summary value emitted alongside the metric name by clickstack_list_metrics or clickstack_describe_source. A metric name can legitimately live in more than one kind (e.g. “container.cpu.usage” appears in both gauge and sum); call this tool once per kind you care about.kind:“summary” is accepted for discovery (attribute keys, sampled values, unit, description), but summary metrics cannot be queried with clickstack_timeseries / clickstack_table — use clickstack_sql against the table in the source’s metricTables.summary.attributeValuesMeta on each kind reports sampledKeys (queried for values) and truncatedKeys (skipped by the per-call sampling cap) — a key in truncatedKeys was never queried, so query it directly if you need its values.Workflow: clickstack_list_sources → clickstack_list_metrics → clickstack_describe_metric → clickstack_timeseries|clickstack_table.Input Parameters
Clickstack describe source
Clickstack describe source
CLICKHOUSE_MCP_CLICKSTACK_DESCRIBE_SOURCECALL THIS BEFORE WRITING QUERIES — prevents unknown-column errors.Returns the full column schema, map-attribute keys, and sampled low-cardinality values (e.g. SeverityText, StatusCode, ServiceName) for a single data source.Workflow: call clickstack_list_sources first to get source IDs, then call this tool for each source you plan to query.Returns:- columns[]: column name, ClickHouse type, and JS type
- mapAttributeKeys: discovered keys in Map columns (e.g. SpanAttributes, ResourceAttributes)
- lowCardinalityValues: sampled values for LowCardinality(String) columns (SeverityText, StatusCode, ServiceName, etc.) — use these in filters instead of guessing
- mapAttributeValues: sampled top values for the most common map attribute keys (e.g. ResourceAttributes[‘service.name’] top values) — requires rollup tables
- requiredSourceFilters: when present, every query against this source MUST pass
sourceFiltersfor each listed column. Sample values for each are returned assourceFilterValues(capped); use clickstack_get_source_filter_values for the full paginated list.
Input Parameters
Clickstack emerging signals
Clickstack emerging signals
CLICKHOUSE_MCP_CLICKSTACK_EMERGING_SIGNALSDetect what is NEW or GONE between an earlier baseline window and a current window — log/event patterns that emerged, ramped up, or stopped. This answers “what changed / what is novel?” — NOT “what attribute value differs?”.USE THIS for status checks, health reports, post-deploy diffs, and any “call out anything new or worth a closer look” question. It mines event patterns (Drain) in BOTH windows and set-differences them:- emerging: patterns whose share of the window is >= minShareRatio× higher now than in baseline (includes brand-new templates absent from baseline)
- disappeared: patterns that were common in baseline but >= minShareRatio× rarer (or absent) now
Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack event deltas
Clickstack event deltas
CLICKHOUSE_MCP_CLICKSTACK_EVENT_DELTASRank the properties of two row groups (logs or trace spans) by how much their value distributions differ. Same algorithm as the in-app Event Deltas view (DBDeltaChart). High-cardinality fields (IDs, request IDs, timestamps) are filtered out by default so the ranking surfaces the categorical attributes that actually separate the two groups. Score is computed after normalizing each group to 100% so it’s robust to different group sizes.USE THIS INSTEAD OF MANUAL PIVOTS. When two row sets visibly differ and you don’t know which attribute(s) separate them, the standard agentic move is to run a GROUP BY for each candidate attribute and compare. event_deltas does this for ALL attributes in one call, ranked by signal strength — usually 1 call instead of 5–20.NARROW the target to the specific outlier rows. A broad target mostly contains healthy rows, so the ranking comes back noisy. The narrower target — the sharper the ranking.TYPICAL USES (any source — logs or traces):- Slow vs fast spans (MOST COMMON for latency triage): target = {where: <op-filter> AND Duration > <threshold>}, baseline = {where: <op-filter> AND Duration <= <threshold>} Scope BOTH to the same operation/endpoint via
<op-filter>; the ranked attribute(s) are then what discriminates the slow invocations of THAT operation from the fast ones. Skipping the op-filter gives a noisy “which operation is slow” answer instead of “which sub-set of one operation is slow”. - Before vs after a deploy / incident onset: target = {window: after onset}, baseline = {window: before onset}
- Failing vs succeeding rows: target = {where: <failing filter>}, baseline = {where: <succeeding filter>}
- One service / endpoint vs the rest: target = {where: ServiceName=X}, baseline = {where: ServiceName != X} Any pair of row sets over the same source works — the tool just asks “what is statistically different about target vs baseline”.
value, targetPct, baselinePct, and diffPct. topDeltas already contains the full per-value comparison for that attribute, so there is no separate target/baseline distribution to consult.IMPORTANT — DO NOT STOP AT RANK 1. The top ~5 ranked properties are often INDEPENDENT axes that together explain the population shift (e.g. a regression localized on the intersection of two attributes). Scan down the list until the score visibly drops to noise level; any property well above that floor is a candidate axis to combine with the others.Input Parameters
hidden array. Default: false (mirrors UI behavior — these are noisy).requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack event patterns
Clickstack event patterns
CLICKHOUSE_MCP_CLICKSTACK_EVENT_PATTERNSDiscover the most common log messages and event patterns. Samples random events, clusters them using the Drain algorithm, and returns patterns sorted by frequency with estimated counts and time trends.PREFER THIS TOOL over clickstack_search or clickstack_table when the goal is to understand what kinds of messages, errors, or events exist — e.g. “sample logs”, “what errors are happening”, “show me common messages”, “what does this service log”. It returns frequency-ranked patterns instead of raw rows, giving a much better overview.Also use when asked about “top patterns”, “common logs”, “noisy services”, “recurring messages”, or log noise analysis.Each pattern includes a “whereSnippet” — use it as the “where” parameter in a follow-up clickstack_search call to browse matching raw events.Requires sourceId — call clickstack_list_sources then clickstack_describe_source first.PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query).When to use which tool:- clickstack_event_patterns: clustering / recurring shapes / noise analysis
- clickstack_search: raw individual rows
- clickstack_table: aggregated metrics / counts / top-N
Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack get alert
Clickstack get alert
CLICKHOUSE_MCP_CLICKSTACK_GET_ALERTWithout an ID: list all alerts as a high-level summary (id, name, displayName, tags, state, source, interval). Optionally filter by state (e.g. state=“ALERT” for firing alerts). With an ID: get full alert detail including configuration, displayName, tags, and recent evaluation history.Input Parameters
Clickstack get dashboard
Clickstack get dashboard
Clickstack get dashboard tile
Clickstack get dashboard tile
CLICKHOUSE_MCP_CLICKSTACK_GET_DASHBOARD_TILERetrieve a single tile from a dashboard by tileId. Useful for inspecting one tile without loading the full dashboard. Use clickstack_get_dashboard (without an ID) to list dashboards, then clickstack_get_dashboard (with an ID) to see all tile IDs.Input Parameters
Clickstack get saved search
Clickstack get saved search
Clickstack get source filter values
Clickstack get source filter values
CLICKHOUSE_MCP_CLICKSTACK_GET_SOURCE_FILTER_VALUESList the available values for the required source filter columns on a single source. Use this BEFORE calling any query tool against a source whose configuration declares requiredSourceFilters. ONLY use this for sources that have requiredSourceFilters. Every such source requires values for every declared column on every query call, and this tool tells you which values exist.Workflow:- clickstack_list_sources or clickstack_describe_source to see whether a source declares requiredSourceFilters and which columns it requires.
- clickstack_get_source_filter_values to fetch the values for those columns.
- Call your query tool with the sourceFilters parameter set, e.g. sourceFilters: { “<columnA>”: [“val1”], “<columnB>”: [“val2”] }
selectedFilters with the values you have already chosen for some columns to narrow the option list for the others.PAGINATION: each column reports totalAvailable, truncated, and (when truncated) nextOffset. Use limit + offset to step through high-cardinality columns instead of pulling everything at once.Input Parameters
requiredSourceFilters. Use clickstack_list_sources or clickstack_describe_source to see which sources have requiredSourceFilters and the column names they expose.Clickstack get webhook
Clickstack get webhook
CLICKHOUSE_MCP_CLICKSTACK_GET_WEBHOOKList available webhook destinations (id, name, service type). Use the returned id as the webhookId when creating alerts with clickstack_save_alert.Clickstack list metrics
Clickstack list metrics
CLICKHOUSE_MCP_CLICKSTACK_LIST_METRICSDISCOVERY: Use this after clickstack_describe_source when you need more metric names than the per-kind sample shows, or when you want to narrow by kind / name pattern / time window. Returns paginated metric names per kind (gauge/sum/histogram/exponential histogram/summary) with optional unit and description (when the OTel-default columns are present). Pass the returned nextCursor back unchanged to fetch the next page.Summary metrics are listed for discovery only — they cannot be passed to clickstack_timeseries / clickstack_table; query them with clickstack_sql against the table in the source’s metricTables.summary.Workflow: clickstack_list_sources → clickstack_describe_source → clickstack_list_metrics → clickstack_describe_metric → clickstack_timeseries|clickstack_table.Input Parameters
nextCursor. Pass it back unchanged to get the next page.Clickstack list sources
Clickstack list sources
CLICKHOUSE_MCP_CLICKSTACK_LIST_SOURCESList all data sources (logs, metrics, traces) and database connections available to this team. Returns source IDs, names, kinds, and connection IDs as a lightweight catalog. Metric sources additionally include metricNamesPreview — a sample of recently-reported metric names per kind — so metrics can be queried immediately.NEXT STEP: After identifying the source(s) you need, call clickstack_describe_source with the sourceId to get the full column schema, attribute keys, and sampled values. This two-step approach avoids fetching expensive schema details for sources you do not need.REQUIRED SOURCE FILTERS: when a source has requiredSourceFilters, every query against it MUST supply values for every column in requiredSourceFilters via the sourceFilters parameter. Call clickstack_get_source_filter_values to discover the available values, or check the sampled sourceFilterValues returned by clickstack_describe_source.NOTE: For most queries, use source IDs with clickstack_timeseries, clickstack_table, clickstack_search, or clickstack_event_patterns. Connection IDs are only needed for clickstack_sql (raw ClickHouse SQL).Metric sources may list a “summary” table in metricTables. Summary metrics are not supported by the builder tools — use clickstack_sql to look at them.Clickstack list teams
Clickstack list teams
CLICKHOUSE_MCP_CLICKSTACK_LIST_TEAMSList all teams the current user belongs to and identify which team is active for this session. Use this to discover available teams when the user works across multiple teams.To switch teams, the MCP client must include the x-hdx-team HTTP header set to the target team ID on subsequent requests. The header is validated against the user’s team memberships — requests for teams the user does not belong to will be rejected.Clickstack patch dashboard
Clickstack patch dashboard
CLICKHOUSE_MCP_CLICKSTACK_PATCH_DASHBOARDMake targeted updates to a dashboard without resubmitting the full object. You can update dashboard-level fields (name, tags) and/or replace a single tile by tileId — all in one call. Unmentioned tiles and fields are preserved. Use clickstack_get_dashboard_tile to inspect a tile before patching it. IMPORTANT: After patching a tile, run clickstack_query_tile to confirm the query still works.Input Parameters
tile. Obtain tile IDs from clickstack_get_dashboard.Clickstack query tile
Clickstack query tile
CLICKHOUSE_MCP_CLICKSTACK_QUERY_TILEExecute the query for a specific tile on an existing dashboard. Useful for validating that a tile returns data or for spot-checking results without rebuilding the query from scratch. Use clickstack_get_dashboard with an ID to find tile IDs.SOURCE FILTERS: when the tile reads a source that declares requiredSourceFilters (core filters) but carries no tile-level sourceFilters of its own (which is the recommended default), pass sourceFilters here to stand in for the dropdown selection so the validation query has values to run with. The values you pass are used only for this query and are NOT persisted on the tile. If the tile already pins its own tile-level sourceFilters, do NOT pass sourceFilters here: omit it so the validation runs with the tile’s own values. Anything you pass here takes precedence over the tile-level values (the two are never merged), so passing a different set would validate something other than what the tile will actually use.Input Parameters
requiredSourceFilters but the tile itself carries no sourceFilters. They are used only for this query (NOT persisted). These take precedence over any tile-level sourceFilters (the two are never merged), so the set that applies must satisfy every required column on its own. If the tile already pins its own tile-level sourceFilters, OMIT this so the query validates the tile as it will actually run. Call clickstack_get_source_filter_values to discover valid values. Ignored for sources without requiredSourceFilters.Clickstack query tiles
Clickstack query tiles
CLICKHOUSE_MCP_CLICKSTACK_QUERY_TILESRun the queries for many tiles of a dashboard in ONE call and return a compact per-tile success/failure summary. This is the efficient way to validate an entire dashboard after clickstack_save_dashboard — prefer it over calling clickstack_query_tile once per tile. Accepts a dashboard ID and an optional list of tile IDs. Markdown tiles are excluded by default; a markdown tile passed explicitly in tileIds is returned with status “skipped”. A tile that fails is reported inline with its error and the overall call still succeeds, so one broken tile does not hide the rest, and unrecognized tile IDs come back as unknownTileIds rather than failing. At most 50 tiles run per call; any beyond that are returned as unrunTileIds — call again with those as tileIds to run the remainder. Drill into a specific failing tile with clickstack_query_tile.Input Parameters
Clickstack save alert
Clickstack save alert
CLICKHOUSE_MCP_CLICKSTACK_SAVE_ALERTCreate a new alert (omit id) or update an existing one (provide id). Alerts monitor a saved search, a dashboard tile, or an inline chart config (source “inline” + chartConfig — no saved search or dashboard needed) and fire when the metric crosses a threshold. At least one webhook notification channel is required: pass “channels” for 1-10 targets, or the legacy singular “channel” for one. Updates replace the alert configuration rather than merging it, so read the alert first and resend its full “channels” array to avoid dropping channels you did not mean to remove.Input Parameters
Clickstack save dashboard
Clickstack save dashboard
CLICKHOUSE_MCP_CLICKSTACK_SAVE_DASHBOARDCreate a new dashboard (omit id) or update an existing one (provide id). Call clickstack_list_sources first to obtain sourceId and connectionId values. IMPORTANT: After saving a dashboard, always run clickstack_query_tiles to validate every tile in one call (or clickstack_query_tile for a single tile) and confirm the queries work and return expected data. Tiles can silently fail due to incorrect filter syntax, missing attributes, or wrong column names. TIP: To update a single tile without resubmitting all tiles, use clickstack_patch_dashboard instead.Input Parameters
filters: [{ expression: "X", ... }], this array MUST declare a filter whose expression is “X”. Otherwise the value is dropped on arrival and the destination opens unfiltered. Two filter types: QUERY_EXPRESSION queries its dropdown values from a source column, while STATIC_LIST declares them inline via options and is always variable-only (it has no expression to broadcast). A QUERY_EXPRESSION filter runs in one of two modes (or both). BROADCAST (the default) applies the selected value as a condition on matching tiles with no per-tile wiring. VARIABLE (isVariableEnabled) exposes the value to tile queries as $variableName, which the tile must reference explicitly. Prefer broadcast; reach for a variable in advanced cases. Enabling both on one filter applies the value twice. By default, a broadcast filter applies to every tile on the dashboard. On mixed-source dashboards, use variable mode or the optional appliesToSourceIds field to restrict a filter to only the tiles whose source carries the referenced column — leave appliesToSourceIds omitted to keep the broadcast-to-all-tiles default. appliesToSourceIds does NOT scope variable references; any tile may reference any variable. Example (broadcast to every tile, the common case): [ { “type”: “QUERY_EXPRESSION”, “name”: “Service”, “expression”: “ServiceName”, “sourceId”: “<trace-source-id>”, “whereLanguage”: “sql” } ] Example (scoped on a mixed log/trace/metric dashboard): [ { “type”: “QUERY_EXPRESSION”, “name”: “Service”, “expression”: “SpanName”, “sourceId”: “<trace-source-id>”, “whereLanguage”: “sql”, “appliesToSourceIds”: [“<trace-source-id>”] } ] Example (variable only, referenced by tiles as $service): [ { “type”: “QUERY_EXPRESSION”, “name”: “Service”, “expression”: “ServiceName”, “sourceId”: “<trace-source-id>”, “whereLanguage”: “sql”, “isBroadcastEnabled”: false, “isVariableEnabled”: true, “variableName”: “service” } ] A tile then uses it as $__filter(ServiceName, $service) in a SQL where clause, which expands to 1=1 while nothing is selected. Example (static list: fixed hand-authored values, always a variable, no source query): [ { “type”: “STATIC_LIST”, “name”: “Environment”, “options”: [“prod”, “staging”, “dev”], “variableName”: “env” } ] A tile references it as $__filter(ResourceAttributes[‘deployment.environment’], $env). Always pass the column explicitly: the one-argument $__filter($env) form reuses the filter’s own expression, which a static filter does not have. Prefer STATIC_LIST when the values are a fixed business list or a curated subset rather than derivable from the data. Example (dependent filter: the Endpoint dropdown only lists the selected service’s endpoints): [ { “type”: “QUERY_EXPRESSION”, “name”: “Service”, “expression”: “ServiceName”, “sourceId”: “<trace-source-id>”, “whereLanguage”: “sql”, “isVariableEnabled”: true, “variableName”: “service” }, { “type”: “QUERY_EXPRESSION”, “name”: “Endpoint”, “expression”: “SpanName”, “sourceId”: “<trace-source-id>”, “whereLanguage”: “sql”, “where”: ”$__filter(ServiceName, $service)” } ] A filter’s where scopes only the values ITS dropdown offers; it is not applied to any tile. That is why Service keeps broadcasting here: its variable is read by the Endpoint dropdown, not by a tile, so the value is never applied twice.collapsed is required. collapsible and bordered are optional and persisted absent when omitted; the renderer treats absence as true. Two or more tabs render as a tab bar; zero or one tab renders as a plain group header. Example: [ { “id”: “service-health”, “title”: “Service Health”, “collapsed”: false, “tabs”: [ { “id”: “errors”, “title”: “Errors” }, { “id”: “latency”, “title”: “Latency” } ] }, { “id”: “overview”, “title”: “Overview”, “collapsed”: true } ]Clickstack save saved search
Clickstack save saved search
CLICKHOUSE_MCP_CLICKSTACK_SAVE_SAVED_SEARCHCreate a new saved search (omit id) or update an existing one (provide id). A saved search stores a reusable query against a data source. Use clickstack_list_sources to find the sourceId.Input Parameters
allowAll: true; using it on any other column is rejected.Clickstack save source
Clickstack save source
CLICKHOUSE_MCP_CLICKSTACK_SAVE_SOURCECreate a new data source (omit id) or update an existing one (provide id) so shipped telemetry becomes queryable. Update is a full replace of the source definition. Required for all kinds: kind, name, connection, databaseName, tableName, timestampValueExpression. Kind-specific requirements: log & trace need defaultTableSelectExpression; trace also needs durationExpression, traceIdExpression, spanIdExpression, parentSpanIdExpression, spanNameExpression, spanKindExpression; session needs traceSourceId; metric needs metricTables and resourceAttributesExpression. Get connection and source IDs from clickstack_list_sources.Input Parameters
name is the column of the source table that selected values are matched against. Set the optional valueExpression to a SQL expression over the filter-values table when the available options live in a differently-named column, or must be transformed to match the source column (e.g. lower(service_name)).Clickstack save webhook
Clickstack save webhook
CLICKHOUSE_MCP_CLICKSTACK_SAVE_WEBHOOKCreate a new webhook (omit id) or update an existing one (provide id). Use the returned id as the webhookId when creating alerts with clickstack_save_alert. Required: name, service (slack, generic, or incidentio), and url. For the slack service the url host must end in slack.com and headers/queryParams/body are not supported. On update, readable fields (description, body) are a full replace while write-only headers/queryParams are preserved when omitted (send {} to clear); changing the destination clears omitted write-only secrets.Input Parameters
Clickstack search
Clickstack search
CLICKHOUSE_MCP_CLICKSTACK_SEARCHBrowse individual log/event/trace rows. Use this when you need to see raw events, investigate specific log lines, or drill into individual records matching a filter.PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query).Requires sourceId — call clickstack_list_sources then clickstack_describe_source first.For aggregated metrics, use clickstack_table instead. For pattern discovery, use clickstack_event_patterns instead.Set denoise=true to automatically filter out high-frequency repetitive patterns, surfacing only unusual or interesting events.Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes[‘http.method’].SOURCE FILTERS: when the source declares requiredSourceFilters (see clickstack_describe_source / clickstack_list_sources), you MUST pass sourceFilters with at least one value for every required column.Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack search dashboards
Clickstack search dashboards
Clickstack sql
Clickstack sql
CLICKHOUSE_MCP_CLICKSTACK_SQLExecute raw ClickHouse SQL. LAST-RESORT TOOL — do NOT reach for this first.Default to the builder tools for querying; they are more reliable and produce richer, structured results: • clickstack_table — aggregations, top-N, single-value KPIs, breakdowns • clickstack_timeseries — trends / metrics over time • clickstack_search — browsing individual log/trace rows • clickstack_event_patterns — recurring log/event pattern discovery • clickstack_event_deltas — attributes that differ between two row groups • clickstack_emerging_signals — patterns new or gone vs a baseline window • clickstack_trace_waterfall — one trace as a parent/child span tree • clickstack_trace_top_time_consuming_operations — slowest child operations in a traceONLY use raw SQL when the query genuinely cannot be expressed by a builder tool — i.e. it requires JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query). 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.Requires connectionId — call clickstack_list_sources to find connections. Call clickstack_describe_source to discover column names before writing SQL.SOURCE FILTERS: when querying a table backed by a registered source, pass sourceId so the $__sourceTable and $__filters macros resolve. If that source declares requiredSourceFilters, you MUST also pass sourceFilters AND include $__filters in your WHERE clause. Source filter values are rendered as <column> IN (<value>, <value2>, ...) conditions.Results are always returned as table rows — for time-series semantics, include a time column and ORDER BY it in your SQL.Input Parameters
column IN (…) predicates derived from the provided sourceFilters. Resolves to (1=1) when there are no source filters. REQUIRED in the WHERE clause when querying a source with requiredSourceFilters (see SOURCE FILTERS below). Requires sourceId. $__sourceTable — expands to the source’s database.table. Requires sourceId. {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters Example (time-series): SELECT $__timeInterval(TimestampTime) AS ts, ServiceName, count() FROM $__sourceTable WHERE $__timeFilter(TimestampTime) AND $__filters GROUP BY ServiceName, ts ORDER BY ts Example (table): SELECT ServiceName, count() AS n FROM otel_logs WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) GROUP BY ServiceName ORDER BY n DESC LIMIT 20requiredSourceFilters (see clickstack_list_sources / clickstack_describe_source) or when using the $__filters or $__sourceTable macros. When set, sourceId’s connection must match connectionId.requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack table
Clickstack table
CLICKHOUSE_MCP_CLICKSTACK_TABLECompute aggregated metrics as a table, single number, pie chart, or bar chart. Use this for grouped aggregations, top-N queries, single-value KPIs, or proportional breakdowns.PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query).Requires sourceId — call clickstack_list_sources then clickstack_describe_source first.Use the top-level “where” to scope the entire query (e.g. filter by service). Each select item can also have its own “where” for per-metric cohort comparisons (compiles to <aggFn>If(…)). Both can be used together.Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes[‘http.method’]. Map attributes work in groupBy and valueExpression, including toFloat64OrZero(SpanAttributes[‘key’]).Shape auto-upgrade: if shape is “number”, “pie”, or “bar” but select has >1 item, it is transparently upgraded to “table”.── METRIC SOURCES ── When sourceId is a metric source, each select item MUST set metricType (“gauge”|“sum”|“histogram”|“exponential histogram”) and metricName (the OTel metric name). valueExpression defaults to “Value” — set it explicitly only to transform the value. Discovery: clickstack_describe_source returns a per-kind metric-name sample; clickstack_list_metrics paginates the full catalog; clickstack_describe_metric returns attribute keys + sampled values for a single metric. Per kind: gauge uses last_value/avg/min/max; sum uses aggFn:“increase” for counter increase (top-N capped at 20 groups when combined with groupBy), or sum/avg on the rate; histogram and exponential histogram use aggFn:“quantile” + level for percentiles, or aggFn:“count” for total bucket count. summary metrics are not supported by the query renderer — query them with clickstack_sql against the table in the source’s metricTables.summary.SOURCE FILTERS: when the source declares requiredSourceFilters (see clickstack_describe_source / clickstack_list_sources), you MUST pass sourceFilters with at least one value for every required column.Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack timeseries
Clickstack timeseries
CLICKHOUSE_MCP_CLICKSTACK_TIMESERIESPlot metrics over time as a line or stacked bar chart. Use this when you need to visualize trends, compare time-series, or monitor metric changes over a time window.PREFER THIS over clickstack_sql. Only drop to raw SQL for things the builder tools cannot express — JOINs, sub-queries, CTEs, window functions, tables not registered as sources, or summary-type metrics (the metricTables.summary table on a metric source, which the builder tools cannot query).Requires sourceId — call clickstack_list_sources then clickstack_describe_source first. Each select item defines one plotted series.Column naming: top-level columns are PascalCase (Duration, StatusCode). Map attributes use bracket syntax: SpanAttributes[‘http.method’].── METRIC SOURCES ── When sourceId is a metric source, each select item MUST set metricType (“gauge”|“sum”|“histogram”|“exponential histogram”) and metricName (the OTel metric name). valueExpression defaults to “Value” — set it explicitly only to transform the value. Discovery: clickstack_describe_source returns a per-kind metric-name sample; clickstack_list_metrics paginates the full catalog; clickstack_describe_metric returns attribute keys + sampled values for a single metric. Per kind: gauge uses last_value/avg/min/max (or aggFn:any + isDelta:true for Prometheus-style delta); sum uses aggFn:“increase” for the counter increase, or sum/avg on the computed rate; histogram and exponential histogram use aggFn:“quantile” + level for percentiles, or aggFn:“count” for total bucket count. TOP-N CAP: aggFn:“increase” + groupBy is capped at 20 groups by the renderer (top by max bucket sum). Narrow with where/groupBy to see other groups. summary metrics are not supported by the query renderer — query them with clickstack_sql against the table in the source’s metricTables.summary.SOURCE FILTERS: when the source declares requiredSourceFilters (see clickstack_describe_source / clickstack_list_sources), you MUST pass sourceFilters with at least one value for every required column.Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack trace top time consuming operations
Clickstack trace top time consuming operations
CLICKHOUSE_MCP_CLICKSTACK_TRACE_TOP_TIME_CONSUMING_OPERATIONSGiven a parent-span filter and a time window, return the child operations contributing the most cumulative time across all traces matching the parent filter. Same algorithm as the in-app “Top Most Time Consuming Operations” chart on the service dashboard.WHAT IT DOES (two-stage, runs as one SQL):- Pick distinct TraceIds where the parent span matches
parentFilterin the window. Optionally restrict tominParentDurationMsto focus on slow parents. - Aggregate ALL spans across those traces (excluding the matching root span itself) by (ServiceName, SpanName), ranked by
total_time_msDESC.
minParentDurationMs to the threshold above which a parent span counts as “slow” for your investigation.MULTIPLE OPERATIONS SLOW: when more than one operation shows elevated latency, call this tool ONCE PER (service, operation) and compare the top child rows across the result sets. Operations with the same top child likely share a cause; operations with different top children are independent regressions that happen to co-occur. DO NOT merge multiple operations into a single parentFilter — the cumulative rank then conflates independent investigations into one noisy answer.RANKING METRIC: total_time_ms = sum(Duration) across all matching child spans. This captures the true contribution to elapsed time — a fast-but-frequent child can dominate the latency even if its p99 is unremarkable.RETURNS: array of rows, each with service, operation, total_time_ms, calls, in_parents (how many parent traces contained at least one such span), p50_ms, p99_ms. Plus a summary block with the matched-parent count.NEXT STEP after this tool: once a dominant slow child operation is identified, the canonical follow-up is clickstack_event_deltas with slow-vs-fast spans of THAT child operation as target/baseline (target = {where: SpanName=‘<slow-child>’ AND Duration > X}, baseline = {where: SpanName=‘<slow-child>’ AND Duration <= Y}). The ranked attributes surface what distinguishes slow invocations of the child operation from fast ones.CROSS-SERVICE BREAKDOWN: this tool does NOT scope children to the parent’s service. Slow cross-service calls (database, cache, upstream HTTP) surface naturally — useful for triage.PAIR TOOL: clickstack_trace_waterfall returns ONE concrete trace as a parent/child tree. Use it for an example after this tool’s aggregate breakdown has pointed you at the slow downstream operation.Input Parameters
requiredSourceFilters. Keyed by column name (the values returned by clickstack_get_source_filter_values or the sampled sourceFilterValues from clickstack_describe_source). FORMAT: { “<columnName>”: [“<value1>”, “<value2>”] } Multiple values for one column become a column IN (...) predicate. ALL OPTION: a column may instead be pinned to every value with { “<columnName>”: { “all”: true } }. This is ONLY accepted for columns whose source marks them allowAll: true (see requiredSourceFilters in clickstack_list_sources / clickstack_describe_source, or the allowAll flag from clickstack_get_source_filter_values); using it on any other column is rejected. Prefer explicit values when they’re known. REQUIRED for any source whose summary in clickstack_list_sources or clickstack_describe_source includes requiredSourceFilters. Every column listed there must have at least one value set. Queries that omit a required column are rejected with an error telling you which columns are missing and how to recover. PARTIAL FILTERS: when you supply values for some but not all required columns, the tool will try to auto-resolve the missing columns by looking up values cross-pruned against the ones you provided — if any missing column has exactly one remaining value it is filled in automatically. The resolved set is echoed back as resolvedSourceFilters in the response so you can supply it explicitly on the next call. Ignored for sources without requiredSourceFilters: pass nothing.Clickstack trace waterfall
Clickstack trace waterfall
CLICKHOUSE_MCP_CLICKSTACK_TRACE_WATERFALLFetch all spans in ONE trace and return them as a parent/child waterfall, pre-ordered for human-readable display. Use this for “show me a concrete example trace” or “what happened in trace X” investigations — the tool walks the cascade for you instead of forcing the model to write self-JOINs in raw SQL.NOT THE RIGHT TOOL when the question is “where does the time go across MANY slow traces of operation X” — that is the aggregate question, and the answer is clickstack_trace_top_time_consuming_operations (called per affected (service, operation) with minParentDurationMs). Use this tool only when you want a single concrete example to inspect, or after the aggregate breakdown has already identified a suspicious operation.Two modes:- Specific trace: pass
traceId. Returns every span in that trace. - Auto-pick: pass
pickFilter+pickBy. The tool finds one matching trace (slowest / first_error / most_recent) and returns its full tree.
summary section with the picked TraceId, total span count, and root span info.When the trace source has a linked logSourceId (the standard config), the response also includes a logs[] array of correlated log rows that share the same TraceId — sorted by timestamp, each carrying its spanId so the agent can attribute messages to specific spans. Disable with includeLogs:false. If the log source declares requiredSourceFilters, include its columns in sourceFilters too (one map shared with the trace source, matched by column name).Prefer this over running raw SQL with JOINs on TraceId — it uses the source’s configured traceIdExpression / parentSpanIdExpression / spanIdExpression so attribute extraction stays consistent with the rest of the platform.PAIR TOOL: clickstack_trace_top_time_consuming_operations is the aggregate counterpart — given a parent-span filter, it ranks child operations by total time across MANY matching traces. Use that when the question is “where does time go in slow X” (aggregate), and use THIS tool when the question is “show me one example of a slow X” (single trace).Input Parameters
ServiceName:<some-service>, ServiceName:<svc> AND SpanName:"<some-operation>", StatusCode:<status-value> (status values come from the source schema’s keyColumns). Ignored when traceId is provided.logs[]. Each log row carries its spanId so the agent can attribute messages to specific spans. No-op if the trace source has no logSourceId configured.requiredSourceFilters. Every column the trace source requires must have at least one value Logs will be skipped if any log source required filter is not provided.Call clickstack_get_source_filter_values to discover valid values. Ignored for sources without requiredSourceFilters.