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.

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

Bracket balance check: every edit operation runs a balance check on the affected file. If unclosed or unmatched {}, (), or [] are detected, a ⚠ SYNTAX warning is returned alongside the successful edit result. This catches broken structure immediately rather than at preview time.

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.