MCP connection

The QuestDB MCP bridge (@questdb/mcp-bridge) is a local stdio MCP server that connects coding agents to a running Web Console. The agent gets tools to explore your database schema, run SQL, and build notebooks with charts and live dashboards. Every action executes in the browser through your already-authenticated console session: the bridge runs on your machine, listens on loopback only, and never handles credentials.

The setup wizard detects and configures Claude Code, Codex, Cursor, OpenCode, and Gemini CLI. Any other MCP client works with the manual configuration.

tip

No coding agent? The built-in AI Assistant has the same capabilities: it builds notebooks and dashboards from a prompt right inside the console, using your own API keys or a local model.

Setup​

One command configures the bridge for every supported agent on your machine; the only prerequisite is Node.js, which provides npx. Each Web Console version expects a specific bridge version: click the MCP status pill at the bottom of the Web Console to see the setup command for your console, already pinned to the expected version.

Copy the setup command from the MCP status pill and run it in your terminal:

npx @questdb/mcp-bridge@<expected-version> setup

The wizard detects your installed coding agents, lets you pick which ones to configure, and writes the bridge into each agent's MCP config, pinned to that version.

The bridge reads these environment variables:

VariableDefaultDescription
CONSOLE_ORIGINhttp://127.0.0.1:9000Web Console origin to pair with.
MCP_BRIDGE_PORTauto-allocatedFixed WebSocket port for the bridge.
LOG_PATH/tmp/questdb-mcp-bridge/…Log file location.
LOG_LEVELINFODEBUG adds heartbeats and full tool payloads.

Pairing​

Before any tool works, your browser has to pair with the bridge. The agent drives the flow, and you do not need the Web Console open beforehand: when the agent needs to pair, the bridge opens a pairing link in your default browser, and the Web Console shows a consent prompt where you review the connection, pick a permission level, and connect.

If the automatic open does not reach the right browser, the agent also shows the pairing credentials so you can pair yourself:

  • Click the deep link it surfaces to open the pairing prompt in your browser.
  • Or paste the WebSocket URL and token into the MCP status pill at the bottom of the console.
The MCP bridge pairing consent prompt in the Web Console

Each bridge run generates a fresh pairing token, held only in memory. By default, the bridge also auto-allocates a port; when MCP_BRIDGE_PORT is set, it uses that fixed port instead. If the console and bridge versions do not match, the consent prompt tells you which bridge version to run.

Permission levels​

You choose what the agent is allowed to see and do when you accept the pairing, and you can change it at any time from the MCP status pill in the footer.

LevelWhat the agent gets
NoneNotebook, query-validation, and documentation tools. Direct database schema tools and query-result rows are unavailable; existing notebook SQL and markdown remain visible to the agent.
Schema accessThe table list, column definitions, and table statistics.
ReadSchema access, plus ad-hoc DQL queries that return result rows to the agent.
WriteRead, plus DDL and DML execution (CREATE, INSERT, UPDATE, DROP).
The four MCP bridge permission levels in the pairing prompt

Permissions are enforced by the Web Console, not by the bridge or the agent. The console classifies every SQL statement before execution and does not let DDL/DML run unless the Write permission is given.

At every level, the agent can still run read-only cells inside a notebook. The results render in your console, but the rows are never returned to the agent.

What agents can do​

Once paired, the agent has tools covering several areas:

  • Schema exploration: list tables and materialized views, fetch DDL, and read runtime table statistics.
  • SQL execution: run ad-hoc queries with results returned to the agent (100 rows by default, up to 10,000, capped at about 1 MB per response), and validate query syntax without executing.
  • Documentation lookup: built-in reference for QuestDB functions, operators, and SQL keywords, so generated SQL uses correct QuestDB syntax without web searches.
  • Notebooks: create, duplicate, and archive notebooks; add, edit, move, and run SQL and markdown cells; switch cells to chart mode with nine chart types (line, area, step line, step area, bar, stacked bar, scatter, pie, candlestick); arrange cells into a grid dashboard; and set per-cell or notebook-wide chart auto-refresh.
  • Two-way handoff: hand analysis back and forth with the agent; it snapshots the workspace and fetches a digest of your recent edits, so you can both work on the same notebook without conflicts.

Background edits​

The agent builds and edits notebooks without taking over the console. New notebooks are created as background tabs, and when an agent changes a notebook you are not looking at, the console shows a "New changes from the agent" notification with a View action that jumps to the change, while the MCP status pill signals the pending changes.

The 'New changes from the agent' notification in the Web Console

Example: An FX dashboard from one prompt​

With the bridge configured and QuestDB running, a single prompt is enough for a full technical-analysis dashboard:

Build an FX technical-analysis dashboard for FX symbols ('GBPUSD' by default) for the last 12 hours in my QuestDB Web Console.

Use the fx_trades and market_data tables, along with the related
materialized views.

The charts I'd like to have in the dashboard:

1. Price (OHLC @interval) & Volume: Full-width candlestick and volume chart.
Add the necessary min/max values to the axes so that volume occupies only the bottom ~20% of the chart.
2. Trend: SMA20 vs SMA50: Line chart showing the 20-bar and 50-bar moving averages of the close price, ordered properly.
3. Bollinger Bands (20, 2σ): Line chart showing close, mid (SMA20), upper, and lower bands.
4. VWAP vs Close
5. Volume by Side: Stacked bar chart showing volumes categorized by side.
6. RSI (14)
7. MACD (12, 26, 9)
8. ATR (14, bps)

The dashboard should auto-refresh every second.

The agent pairs with the console, loads its QuestDB SQL guidance, validates each indicator query, and builds the whole dashboard in a background tab. You approve the connection once, then click the notification when it is ready:

Next steps​