Each Web Console build is verified against a specific bridge version — EXPECTED_BRIDGE_VERSION (currently "0.1.0") in src/utils/mcp/protocolVersion.ts. On connect the console sends expectedBridgeVersion in the hello frame (src/utils/mcp/MCPBridgeClient.ts:261). The bridge compares majors: different major → WS close 4004 (terminal); same-major drift → it flags versionMismatch but only surfaces it to the coding agent via wait_for_pairing's userMessage (mcp-bridge/src/pairingTools.ts:128-137).
The console UI never tells the user which bridge version to install, nor shows a mismatch:
src/scenes/Footer/MCPBridgeStatus/PairPopover.tsx and src/providers/MCPBridgeProvider/PairingConsentModal.tsx display URL/token/status only.
- The
hello_ack frame carries the bridge's actual version in its v field (src/utils/mcp/types.ts:41-49), but the console ignores it — handleHelloAck and the provider's helloAck handler (src/providers/MCPBridgeProvider/index.tsx:219) don't read msg.v.
Ask
- In the Pair popover, always show the pinned version with a copy-paste install hint, e.g.
npx @questdb/mcp-bridge@<EXPECTED_BRIDGE_VERSION> setup (the README already documents this pin).
- Capture the bridge's reported
v on hello_ack; on same-major drift show a non-blocking warning in the popover/modal; on major mismatch the terminal 4004 error already fires — make its copy actionable with the same install hint.
Background — why versions must match
Tool schemas are duplicated in src/consts/shared-definitions.json and the bridge's copy, kept byte-identical by src/consts/shared-definitions.sync.test.ts. Codex caches the tool list at MCP init and ignores notifications/tools/list_changed, so the bridge must bundle its own copy instead of relying on the console's hello-sent tools. Mismatched versions → schema drift → broken tool calls.
Each Web Console build is verified against a specific bridge version —
EXPECTED_BRIDGE_VERSION(currently"0.1.0") insrc/utils/mcp/protocolVersion.ts. On connect the console sendsexpectedBridgeVersionin the hello frame (src/utils/mcp/MCPBridgeClient.ts:261). The bridge compares majors: different major → WS close4004(terminal); same-major drift → it flagsversionMismatchbut only surfaces it to the coding agent viawait_for_pairing'suserMessage(mcp-bridge/src/pairingTools.ts:128-137).The console UI never tells the user which bridge version to install, nor shows a mismatch:
src/scenes/Footer/MCPBridgeStatus/PairPopover.tsxandsrc/providers/MCPBridgeProvider/PairingConsentModal.tsxdisplay URL/token/status only.hello_ackframe carries the bridge's actual version in itsvfield (src/utils/mcp/types.ts:41-49), but the console ignores it —handleHelloAckand the provider'shelloAckhandler (src/providers/MCPBridgeProvider/index.tsx:219) don't readmsg.v.Ask
npx @questdb/mcp-bridge@<EXPECTED_BRIDGE_VERSION> setup(the README already documents this pin).vonhello_ack; on same-major drift show a non-blocking warning in the popover/modal; on major mismatch the terminal4004error already fires — make its copy actionable with the same install hint.Background — why versions must match
Tool schemas are duplicated in
src/consts/shared-definitions.jsonand the bridge's copy, kept byte-identical bysrc/consts/shared-definitions.sync.test.ts. Codex caches the tool list at MCP init and ignoresnotifications/tools/list_changed, so the bridge must bundle its own copy instead of relying on the console's hello-senttools. Mismatched versions → schema drift → broken tool calls.