QuestDB MCP server that exposes the QuestDB Web Console notebook to coding agents (Claude Code, Codex) over a local WebSocket.
This server defines 2 tools with strong descriptions, well-structured schemas, and clear error handling patterns. Both tools are pairing/authentication focused and follow a deliberate multi-step flow documented in the descriptions. Naming is verb-forward and action-oriented. Schemas are complete with proper type definitions and constraints. However, the server exposes only pairing orchestration tools; the actual functional tools (database queries, schema introspection) are bundled from QuestDB's bridge via shared-definitions.json and not directly visible in this codebase, which limits the assessment scope. The visible pairing tools are high-quality but represent a narrow slice of the server's capabilities.
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 the exact upgrade instruction 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.
Functional tools are bundled externally (shared-definitions.json from QuestDB bridge) and not directly inspectable in this codebase. Tool definitions are loaded dynamically via BUNDLED_FUNCTIONAL_TOOLS. While the pairing tools are well-defined, the actual database operation tools (SQL execution, schema access, etc.) cannot be scored because their schemas and descriptions are not visible in the source provided.
The wait_for_pairing tool description exceeds recommended length (450+ characters vs. baseline 194-char average, p90=392). While exceptionally detailed and necessary for correctness, it risks token overhead in large agent contexts. Consider splitting prerequisites and error scenarios into a separate 'Troubleshooting' section or linking to documentation.
get_pairing_credentials description is also lengthy (340+ chars). While necessary for the mandatory 3-step flow, could be condensed with a link to the protocol documentation for detailed steps.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 68 | <=2025-11-25 | v2 |