blnq MCP Server Spec

Model Context Protocol server for live browser editor integration. Tool listings generated from the shared registry.

Overview

The blnq MCP server connects an external AI harness (Claude Code, Cursor, Windsurf, any MCP-speaking client) to the blnq.studio browser editors in real time. Tool calls from the AI flow through a per-tab bridge and are pushed into the live Monaco editors via Server-Sent Events.

The same bridge is shared with the in-browser AI chat panel, so anything described here applies to both call paths. Edits from either side push to the browser over the same SSE channel.

Quick Start

Three steps. Most people get stuck on step 1 because they assume the agent can see the project before they click Start MCP. It can't — the bridge is lazy by design.

1. Open an editor tab & click Start MCP. Visit blnq.studio/e. In the top-right of the header you'll see a Start MCP button — click it. The button lights up, the bridge connects, and your MCP ID (a random UUID bound to this tab) is copied to your clipboard. Leave the tab open.
2. Add blnq to your AI client. Pick your client in the next section and add the snippet. blnq speaks the standard Streamable HTTP MCP transport at https://blnq.studio/mcp — no API key, no auth header, no install step on the server side.
3. Just start prompting. Say "using blnq, build me X". The agent will hit a tool call that needs a tabId and prompt you for your MCP ID — paste it then. This is often the easiest flow because you don't need to plan ahead. If you prefer, you can hand the ID over upfront ("My blnq MCP ID is abc1234, use it on every tool call") so the agent never has to ask.

Adding blnq to your AI client

Every config below points the client at the same endpoint: https://blnq.studio/mcp over HTTP (Streamable HTTP transport). Pick the one that matches your tool.

Claude Code (CLI)

One command — the CLI writes the config for you:

claude mcp add --transport http blnq https://blnq.studio/mcp

Or add it manually to ~/.claude.json (user scope) or .mcp.json (project scope):

{
  "mcpServers": {
    "blnq": {
      "type": "http",
      "url": "https://blnq.studio/mcp"
    }
  }
}

Verify with claude mcp list; the entry should show connected once you start a session.

Claude Desktop

Open Settings → Developer → Edit Config (this opens claude_desktop_config.json). Add:

{
  "mcpServers": {
    "blnq": {
      "type": "http",
      "url": "https://blnq.studio/mcp"
    }
  }
}

Restart Claude Desktop. If your build doesn't yet support remote HTTP MCP natively, use the mcp-remote stdio bridge instead:

{
  "mcpServers": {
    "blnq": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://blnq.studio/mcp"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in a workspace (per-project), or use Settings → MCP → Add Server:

{
  "mcpServers": {
    "blnq": {
      "url": "https://blnq.studio/mcp"
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json, or use Settings → Cascade → MCP Servers → Add Server:

{
  "mcpServers": {
    "blnq": {
      "serverUrl": "https://blnq.studio/mcp"
    }
  }
}

Any other MCP-compatible client

blnq is a stock Streamable HTTP MCP server. If your client supports remote MCP over HTTP, point it at https://blnq.studio/mcp — nothing else is required. If it only supports stdio, wrap it with mcp-remote as shown in the Claude Desktop fallback above.

Passing the MCP ID

Every tool that touches editor content takes a tabId parameter — that's the MCP ID copied to your clipboard when you clicked Start MCP. There is no discovery tool and no auto-resolution: in a shared-tenant deployment, listing connected tabs would leak other users' projects, so the server requires an explicit ID on every call. You have two ways to get it to the agent.

On-demand (easiest). Just start prompting — "using blnq, build me a portfolio site". The agent will hit its first tool call without a tabId, see the "MCP ID required" error, and ask you for one. Paste it then. You don't have to plan ahead; the harness handles the prompt for you.

Upfront (when you want to skip the round-trip). Paste the ID into the chat at the start of the session and ask the agent to remember it. Examples:

• "My blnq MCP ID is 7f2a-9c1b. Use it as the tabId on every blnq tool call."
• "For all blnq tool calls in this session, tabId is abc1234."

If the ID stops working, you'll see "MCP ID not recognised" from the tool. That means the editor tab was closed (the ID is revoked ~5 minutes after the SSE connection drops). Open a fresh tab at blnq.studio/e, click Start MCP again, and pass the new ID.

Example prompts

Once the agent has your MCP ID, talk to it like any other tool. A few starting points:

Using blnq, build me a one-page portfolio: sticky nav, hero
with my name, three project cards, contact section. Dark
theme, no AI blue, no gratuitous gradients.

Using blnq, read the current files, then make the hero
stack on mobile and add a subtle fade-in for the cards.
Run blnq_check_preview when you're done and fix anything
it flags.

Using blnq, generate three design variants of the landing
page — minimalist, editorial, brutalist — and show them in
the variant picker.

Architecture & lifecycle

The bridge is session-less from the harness's point of view — the only identity that matters is the tabId, a random UUID minted by the editor tab.

┌──────────────────────┐      POST /mcp         ┌──────────────────────┐
│  External AI harness │ ─────────────────────▶ │  blnq MCP server     │
│  (Claude Code, etc.) │ ◀───────────────────── │  (Streamable HTTP)   │
└──────────────────────┘   tool results / SSE   └──────────┬───────────┘
                                                           │
                                                  bridge state
                                                  (per tabId)
                                                           │
                           ┌───────────────────────────────┤
                           │                               │
                  sendToTab(event, data)       POST /api/bridge/sync
                    via SSE channel            (content mirror)
                           │                               │
                           ▼                               │
                ┌──────────────────────┐                   │
                │  Browser editor tab  │ ◀─────────────────┘
                │  (Monaco + preview)  │
                │  /api/bridge/events  │
                └──────────────────────┘

Connection lifecycle (what happens under the hood)

1. User opens an editor tab at blnq.studio/e. The page mints an MCP ID and opens GET /api/bridge/events?tabId=…. This SSE stream is how the server pushes live updates back to the browser.
2. User clicks Start MCP. The browser starts mirroring file content via POST /api/bridge/sync, seeding the in-memory state so external tools can read it. Without this click, the bridge stays idle and tools see no tab.
3. User pastes the MCP ID into the AI client's chat.
4. Harness sends initialize to POST /mcp. The server responds with tool definitions. Session-aware clients get an mcp-session-id header to reuse; stateless clients get a one-shot server per request.
5. Harness calls tools with the MCP ID as the tabId parameter. The server resolves to the matching tab and pushes edits over the SSE channel.

Reading data back from the browser

Some tools need live runtime data, not just editor text — e.g. blnq_run_js, blnq_get_element_info, blnq_check_preview, blnq_click. These use a request / response pattern over SSE:

1. Server sends an SSE event (e.g. js:eval, element:query, dom:action, a11y:run) with the request payload.
2. Browser executes the request in the preview iframe.
3. Browser POSTs the result to a matching endpoint (e.g. /api/bridge/js/results).
4. Server resolves the pending promise; the tool call returns.

Each pending request has a timeout (default 8–15 s depending on tool). Only one pending request per tool type per tab at a time — the new request replaces the old one.

Prerequisites the harness should assume

• At least one editor tab is open at blnq.studio/e.
• The user has clicked Start MCP in the header — the button is lit and the MCP ID is on the clipboard.
• The user has passed the MCP ID to the harness (e.g. in a chat prompt).
• The tab has completed an initial sync (automatic on connect).

MCP Connection Details

The MCP endpoint is at POST /mcp using the Streamable HTTP transport from the official MCP SDK.

• Session-aware clients: send an initialize request without a session header. The server returns an mcp-session-id header — include it on all subsequent requests.
• Stateless clients: send any valid MCP request without a session header. A one-shot server is created per request.
• DELETE /mcp — close an existing session (requires mcp-session-id).
• GET /mcp — returns 405 Method Not Allowed.
• GET /mcp/spec — this page.

Tools

Inspection, preview-driving, and project-state tools. Each tool is tagged read (safe to call without prompting the user) or write (mutates project state). Listings below are generated from the shared registry, so this page can't drift from the live tools.

Multi-File Tools

Projects are a list of files keyed by path (e.g. /index.html, /page2.html, /style.css, /components/nav.js). /index.html is the default entry page and cannot be deleted; additional HTML pages can be created freely and linked with relative <a href="page2.html"> links. Other files are referenced via standard <link> and <script> tags.

Design Variants

The variants flow lets the AI stream multiple design options into the editor's variant picker. Plan N variants, call blnq_set_variants with the first only (the picker appears immediately), then call blnq_append_variants once per remaining variant so the user sees them arrive as they're generated. The first variant loads in the editor; the user can switch or dismiss via the picker UI.

Each variant is a { name, files: [{ filename, content }] } bundle — a complete file set, not a diff. When the user activates a variant, the browser POSTs the selected files to /api/bridge/variant/activate; dismissing the picker POSTs to /api/bridge/variant/clear. The AI can also commit one directly with blnq_select_variant (by number or name) — equivalent to the "Select" button: the server makes that variant the active project, discards the rest, and pushes variants:select so the editor loads it and closes the picker (no confirm dialog).

Panel-only Tools

These tools are not exposed over MCP. They need the in-browser chat panel UI to render their effect (button cards, task lists, skill content), so external clients won't see them. They're listed here for completeness.

The AI Chat Panel & the bridge

The in-browser AI chat panel is the second client of the same bridge. It never touches POST /mcp — it runs server-side in the same process and calls the shared tool registry directly. Everything else (bridge state, SSE pushes, undo history, validation) is identical to the external MCP path, which is why edits from either side look the same to the browser.

┌──────────────────────┐   POST /api/ai/chat    ┌──────────────────────┐
│  Chat panel (browser)│ ─────────────────────▶ │  AI agent loop       │
│                      │ ◀───────────────────── │  (server, in-proc)   │
└──────────┬───────────┘   NDJSON stream        └──────────┬───────────┘
           │                                    shared tool registry
           │                                               │
           │                                      bridge state (tabId)
           │                                               │
           └──────────── SSE /api/bridge/events ◀──────────┘

How a panel turn works

1. Before each turn the browser force-pushes its current content via POST /api/bridge/sync, so the bridge state the tools read is never stale.
2. The panel sends POST /api/ai/chat with { provider, model, messages, tabId, … }. The response is an NDJSON stream of text deltas, tool-call progress, _error, and a final _meta record (usage, step count, checkpoint id).
3. The server runs an agent loop against the chosen provider. Each tool call resolves through the same shared registry documented above — the handlers mutate bridge state and push file:update / file:create / etc. over the same SSE channel external MCP clients use.
4. The turn ends when the model stops calling tools (or calls a terminal tool like blnq_ask_user).

Differences from the external MCP path

• No tabId in the model's hands. The panel knows its own tab, so the server injects tabId into every tool call. The model never sees the parameter — unlike external clients, which must pass the MCP ID explicitly.
• Slightly trimmed tool set. The panel advertises the shared registry minus blnq_get_project_info (redundant — the project name and file list are already injected into the prompt) and minus blnq_web_search when SERPER_API_KEY isn't configured. Panel-only tools (badged above) run via chat-side handlers.
• Live token-level file streaming. For providers that stream tool-call arguments, the server extracts the growing file body from the partial JSON and pushes it via file:stream as it arrives, so code appears in Monaco while the model is still writing. The authoritative content lands via file:create/file:update when the call completes.
• Per-turn checkpoints, separate from undo. Every turn starts with a bridge checkpoint ("Before AI turn"). The panel uses it for the per-turn diff viewer (GET /api/ai/diff) and one-click rewind (POST /api/ai/rewind); POST /api/ai/snapshot creates a pinned manual snapshot. This sits alongside the 30-step undo stack described under Validation & Undo, which both call paths share.
• Panel-side guardrails. The chat loop adds protections external harnesses are expected to bring themselves: a per-request screenshot cap, repeated-read dedup (re-reading an unchanged file returns a short refusal instead of the content), and read-only tools running concurrently.
• Steering. While a run is active the browser can inject mid-turn user messages via POST /api/ai/inject; POST /api/ai/stop aborts the run.

REST / Bridge API

These HTTP endpoints back the MCP tools and are also used directly by the browser client. All endpoints that operate on a tab require tabId (body or query depending on method).

Connection

Content

Variants

Sketch

Accessibility

Console

Cursor

Browser-side result endpoints

These are where the browser POSTs results after responding to an SSE request (the "read data back" pattern described earlier). The harness shouldn't need to call these directly.

SSE Events

The SSE channel at GET /api/bridge/events?tabId=… pushes the following events. The browser client is the only intended consumer — an external harness never opens this stream.

Project File Model

Projects contain multiple files, stored as a JSON array. /index.html is the default entry page (and cannot be deleted); additional HTML pages such as /about.html or /blog/post.html are fully supported. CSS and JS files are referenced with standard <link> and <script> tags.

The preview uses a Service Worker that serves project files from the in-memory map — ES modules, CSS @import, and relative fetch() all resolve natively against a real origin, not srcdoc.

Validation & Undo

Syntax check: every write, edit, and create runs syntax diagnostics on the affected file — JS is parsed with acorn (no false positives from braces in strings or comments), CSS gets a string/comment-aware bracket scan, and HTML has its inline <script>/<style> blocks checked with file-relative line numbers. Errors come back as a ⚠ SYNTAX warning alongside the successful result, so broken structure is caught immediately rather than at preview time.

Tolerant edit matching: find-replace edits match exactly first, then fall back to a cascade of whitespace-, indentation-, and escape-normalized strategies (with anchor-based block matching for multi-line edits). Ambiguous matches are refused with line numbers; fuzzy matches that would span far more text than requested are refused outright. Fuzzy-rescued edits report matchedBy.

Undo history: every write, edit, create, and delete pushes a snapshot onto the per-tab undo stack. The blnq_undo tool restores prior snapshots and reports which files were affected. History is capped at 30 steps per tab.