Get the credentials the user needs to pair their browser with this MCP bridge — calling this tool does NOT itself pair anything. It returns a deep_link, ws_url, token, AND a pre-rendered userMessage with the exact text to show the user. REQUIRED FLOW — do all three in the defined: (1) call this tool, (2) write a message to the user containing the userMessage text (or your own equivalent showing deep_link + ws_url + token), (3) call wait_for_pairing. DO NOT skip step (2). Calling wait_for_pairing without first showing the credentials guarantees a timeout — the user has no credentials to enter, so they cannot pair. By default this also auto-opens the deep link in the user's default browser; pass auto_open_browser:false to suppress that and just return the credentials. Returns paired:true if already paired.

Poll for completion of pairing started by get_pairing_credentials. PREREQUISITE: you have already written a message to the user containing the deep_link + ws_url + token from get_pairing_credentials's last response. If you have NOT yet shown those credentials, do that first — calling this tool without showing credentials only burns 50 s of polling while the user sees nothing actionable. Blocks for timeout_ms (default 50 s, max 50 s — sized to fit under typical MCP client tool-call timeouts). Returns {paired:true, consoleOrigin, permissions:{grantSchemaAccess,read,write}} on success, or {paired:false, reason:'timeout', retryCount, maxRetriesHint:10} on timeout — call again to keep waiting (up to ~10 retries / ~8 min) until the user pairs. If the bridge version doesn't match what the web console expects, the success payload includes a warning, a pre-rendered userMessage, and assistantNextActions; you MUST show the userMessage to the user verbatim AND suggest running the exact npx … upgrade command it contains (offer to run it for them) before proceeding. If pairing is refused outright for an incompatible bridge, the result is {paired:false, reason:'incompatible_bridge', userMessage, assistantNextActions} — show the userMessage verbatim and STOP polling; pairing cannot succeed until the user reinstalls the bridge version named in the message. permissions describes the user-granted MCP scopes: grantSchemaAccess=true allows schema introspection (tables/columns); read=true allows DQL (SELECT/SHOW); write=true additionally allows DDL/DML (CREATE/INSERT/UPDATE/DELETE/DROP/…). Operations outside the granted scope return PERMISSION_DENIED with a message naming the missing scope — adjust your plan accordingly rather than retrying.

Get a list of all tables and materialized views in the QuestDB database

Get the full schema definition (DDL) for a specific table or materialized view

Get the runtime details/statistics of a specific table or materialized view

Validate the syntax correctness of a SQL query using QuestDB's SQL syntax validator. All generated SQL queries should be validated using this tool before responding to the user.

Get a table of contents listing all available QuestDB functions, operators, and SQL keywords. Use this first to see what documentation is available before requesting specific items.

Get documentation for specific QuestDB functions, operators, or SQL keywords. This is much more efficient than loading all documentation.

Create a new QuestDB notebook tab in the editor. You never see query data; this only scaffolds the tab and binds the current chat if it isn't already bound to a notebook. The tab is ALWAYS created in the background — you never switch the user's active tab. The user sees a notification and opens it themselves; only call activate_notebook if they explicitly ask to be taken there.

Switch the user's editor to the given notebook tab so it becomes visible and focused. ONLY call this after the user has explicitly agreed to be taken to the notebook (e.g. they accepted your offer to open it). Never call it to auto-switch while the user is working elsewhere.

Duplicate a notebook tab. Copies every cell (SQL, mode, chart config) and the layout into a NEW notebook labelled " (copy)" placed right after the original; cell ids are regenerated and last-run results are cleared. The copy is ALWAYS made in the background — you never switch the user's active tab. The user sees a notification and opens it themselves; only call activate_notebook if they explicitly ask to be taken there.

Archive (soft-delete) a notebook tab — the same as the user closing it with the X. It moves to history and the user can restore it; it is not permanently destroyed and query data is untouched. If this notebook is bound to the current chat, the binding goes stale (start a new one with create_notebook).

List the cells in a notebook. Returns id, type, short preview (≤120 chars), position, mode, and last-run status. No cell data values.

Get full details of a cell (value, kind via type, UI flags, chart config, last-run status + trimmed error). type:"markdown" marks a prose cell whose value is markdown source; SQL cells omit type. Never includes query result data. By default the value is capped at 4 KB; a capped response carries truncated: true and full_length. A truncated value is NOT the cell's real content — NEVER write it back (update_cell / apply_notebook_state value); re-read with get_full_content: true first, or keep the cell with preserve_value: true.

Full structural snapshot of a notebook (layout, cells with previews, kind via type, last-run statuses). type:"markdown" marks a prose cell; SQL cells omit type. No cell data values; no columns/rows/count. Previews are capped at 120 chars — cells cut carry preview_truncated: true + full_length; a preview is never a cell's real content to write back.

Append a cell to the notebook. Returns the new cell id and, if run=true, a per-query status array. You never see query rows or column data. Set type:"markdown" to add a prose cell instead of a SQL cell — its sql field then carries the markdown source, it is rendered (never executed), and run is ignored.

Replace a cell's value. Overwrites preemptively — cells are auto-saved. Use to fix a broken SQL cell. When editing part of a long cell, base the new value on a non-truncated read (get_cell with get_full_content: true) — never on a preview or a truncated: true read.

Delete a cell from the notebook.

Swap a cell with the one above it.

Swap a cell with the one below it.

Duplicate a cell immediately after the original.

Execute a SQL cell. Each ;-separated statement runs sequentially; if one fails, the remaining statements are NOT attempted. Returns { success, queryCount, results: string[] }, where each results entry is "success", "cancelled", or "ERROR: <message>", in source order. You do NOT see columns, rows, or values — call run_query if you need data. success is true only when every statement reached "success". This is the ONLY path that executes agent-initiated DDL/DML in a cell (apply_notebook_state and add_cell never auto-run writes) — it requires the 'write' permission and the user's consent. A markdown cell is never executed: the response is { ran: false, skipped: true, note: <reason> }.

Switch a notebook between list and grid layouts.

Position a single cell in grid mode. x/y/w/h are integers in the 12-column react-grid-layout grid (w ≤ 12).

Switch a SQL cell between run (table output) and draw (chart output). Draw cells auto-execute — do not call run_cell afterwards. MULTI-SERIES TIP: a draw-mode cell can hold multiple SELECT statements separated by ;. The first query's timestamp column is the chart's x-axis (the 'anchor'); every additional query contributes its numeric columns as extra series merged on the time axis. Use this to overlay metrics that come from different tables or different aggregations on a single chart.

Configure the chart for a draw-mode cell. The cell's ;-separated SELECTs AUTO-COMBINE into one chart sharing the first query's x-axis; queries holds one config per statement (index-aligned). Queries combine when their x-axis kind matches: all-temporal merge by time, all-categorical merge by category name. Each query keeps its own type (line/area/stepLine/stepArea/bar/stackedBar/scatter/pie/candlestick); set axis:"right" (+ optional right_axis) for a series on a different unit/scale; enabled:false opts a query out (the first query is always included — it defines the x-axis). For a candlestick query, supply ohlc:{open,high,low,close} (required — a candlestick needs an explicit ohlc mapping). When x_column is a NUMERIC column (not a timestamp/category) it renders as a continuous value axis. Numeric-x charts are single-query (they don't combine). Patch semantics: top-level x_column/right_axis null = preserve; queries null = preserve; queries: [] clears overrides (back to inference); a non-null queries array REPLACES all per-query configs (send one entry per ;-split statement — a non-empty array whose length differs from the statement count is rejected). pie/scatter/stackedBar only render as a chart of their own (single-query).

Set auto-refresh polling for a draw-mode cell's chart. value: true = adaptive poll (interval auto-tuned to response time), false = no polling, or a fixed interval string ("1s", "5s", "10s", "30s", "1m").

Set or clear a cell's name (its display label in the cell header). Applies to any cell; for a chart cell it is also the chart title. Pass null to clear.

Toggle whether the cell's result view (chart OR table) fills the cell, hiding the editor. Applies to any cell that has a result — not just charts. For narrow cells, there is no split-view. When this is false, the cell only shows the editor for narrow cells. For wide cells, it shows the editor and the result view if result exists.

Bulk-apply the entire desired state of a notebook in one atomic call. Use this for bulk edits spanning multiple cells or creating a notebook from scratch. Use update_cell or set_cell_* for small operations. Use INSTEAD OF chained add_cell + update_cell + set_cell_mode + set_cell_chart_config only when composing a multi-cell layout from scratch, changing many cells at once, or restructuring an existing notebook. The cells array is the COMPLETE desired list: cells in the current notebook whose id is missing from your request are DELETED. For new cells, omit id and one will be generated. Each cell carries exactly one of value (full verbatim SQL) or preserve_value: true (keep the existing cell's SQL, results, and run history unchanged) — prefer preserve_value for every cell whose SQL you are not changing, and NEVER send a value reconstructed from a preview or a truncated get_cell read. Charts in mode='draw' with auto_refresh=true render automatically — do not call run_cell afterwards. Cells with resolved mode='run' (explicit, or omitted: new defaults to 'run', existing preserves) auto-execute after the apply — EXCEPT cells whose statements include DDL/DML (INSERT/UPDATE/CREATE/DROP/...): those are NEVER auto-executed (their runs entry gets skipped: true), so applying state can never trigger a write's side effects. Take consent from the user, then call run_cell explicitly to execute them. Markdown cells (type:"markdown") are rendered prose and are likewise never auto-run. The response includes a runs: [{cellId, success, queryCount?, results?, error?, skipped?}] array — results is the per-statement status list ("success" / "cancelled" / "ERROR: <message>"); a top-level error is set only when the run was refused before any statement executed. Always call get_workspace_state first; the state-freshness gate applies.

Spotlight one cell (or null to restore normal layout). Hides other cells in the notebook view.

Execute an arbitrary SQL statement against the user's QuestDB instance and return the result rows so you can inspect data, validate work, or compose follow-up queries. UNLIKE run_cell, this tool DOES return data values. Default limit is 100 rows; pass limit (max 10000) to request more. The response payload is capped at ~1 MB — rows beyond that are dropped from the tail. The response includes truncated, total_count, and returned_count so you know exactly what was clipped. DDL/DML (CREATE / INSERT / UPDATE / DROP / etc.) is allowed and executes against the live database — be deliberate. Auth + connection are handled by the user's already-authenticated browser session.

If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of each notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.

Return the current workspace + notebook context as text. Use this at the start of every notebook turn so you know which notebook is active, what cells exist, layout mode, chart configs, and last-run statuses. Pass include_user_events=true to also receive the digest of edits the user made since your last fetch.

If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of each notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.

Return the digest of user edits to the notebook since your last fetch (or session start). Use this to detect that the user changed something the agent might want to react to. Coalesced — multiple typing events on the same cell collapse to a single 'edited' entry.