Browser & screenshot loop

The client sees the real confBuild result

In hosted Remote MCP mode, the user’s already signed-in confBuild tab renders by default. Server rendering is a separate explicit option:

1. The MCP client saves the intended project revision.
2. The client calls confbuild_prepare_browser, performs the safe handoff through host Chrome/browser control, and waits for connected: true.
3. confbuild_render_project creates a private browser-tab render job for that user and exact revision by default.
4. The confBuild web app detects the job only in the matching open project.
5. The tab captures the Three.js canvas from the requested views and uploads private PNGs.
6. confbuild_get_render_result returns diagnostics and native MCP image blocks to Codex or Claude.
7. The MCP client—not the server—interprets the images and decides on the next patch.

Requirements for remote screenshots

• The browser is signed in with the same confBuild account that approved MCP OAuth access.
• The requested project is open under /e/… or another supported project route.
• The project, saved configuration, and revision exactly match the MCP target.
• The editor and 3D scene have fully loaded.
• The tab remains open during the render job.

Customer mode requires no browser extension, local Node.js, CDP, or remote debugging.

Asynchronous render sequence

The flow always starts with browser preparation and then uses asynchronous render tools:

1. confbuild_prepare_browser returns reuse, reload, navigate, or open-new; repeat it until confirmed.
2. confbuild_render_project starts the job and returns a renderJobId.
3. Poll confbuild_get_render_result with waitMs until completed or failed; confbuild_render_and_wait combines steps 2 and 3.
4. For multi-part models, follow the returned confbuild_inspect_outputs arguments. One job returns zoomed focus with ghosted surroundings, isolation, an automatic center section, and x-ray.

For structures, up to three distinct connection families are selected from real scene contact pairs. The agent must review every returned group—such as a base plate and anchors, gusset, bracket, or member joint—in separate close-ups for seating faces, hardware, clearances, end cuts, and a continuous load path. A whole-hall or whole-frame overview is insufficient, and detail images of unrelated parts do not satisfy the completion gate.

Example:

{
  "editSessionId": "edit-…",
  "views": ["default", "right", "front", "left"],
  "rendererMode": "browser-tab",
  "timeoutMs": 120000
}

Only persisted data can be rendered. An edit session with uncommitted changes must be validated and committed first.

browser-tab is the default and never switches to server compute automatically. Only after an explicit user request are rendererMode: "server-headless" and serverRenderingExplicitlyRequested: true allowed; browser connection is still mandatory.

Returned views

Up to seven PNGs are available; four are the default:

• default: deterministic perspective view;
• right: view from the right;
• front: front-oriented view;
• left: view from the left.

For directional views, the browser computes visible model bounds, targets the camera and orbit controls at the model, and restores the original camera afterward. These are visual perspectives, not guaranteed orthographic CAD projections or measurement evidence.

PNG previews returned to Codex or Claude preserve their aspect ratio and are limited to 960 × 640 pixels. The result interleaves a caption and native MCP image block for every view in order. The caption identifies the render iteration, view, whole-model or detail context, project, and resolution; presentation.renderIteration exposes the same iteration number structurally. presentation also reports available, returned, and omitted images; omitted images must be retrieved before visual approval.

The four-image inspection set is bound to the exact project and configuration revision. After a repair, repeat it for the same output IDs, then return to the unscoped default, right, front, and left completion render.

Visible MCP status in the editor

During real MCP activity the app shows a compact global badge, including on the dashboard while preparing the browser. It distinguishes active, connecting project tab, waiting for the 3D view, capturing preview, sending preview, sent, and failed. On project routes it remains project-scoped; without current activity or a matching render job it stays hidden.

The local timeline keeps up to 100 steps in a compact scrollbar viewport with an up-arrow for older entries. One render job appears as one iteration gallery containing all available view thumbnails; capture/upload phases and consecutive technical read calls are collapsed by default. A currently running technical subaction also remains expandable beneath the visible main step. Mouse hover or keyboard focus opens a larger preview with view, resolution, source dimensions, file size, client, and reported model. The project-scoped text history survives reloads for up to 24 hours in sessionStorage; error text, reasoning, tab IDs, image bytes, and Blob URLs are not persisted. UI images remain available only inside the current browser tab and are released when the route or user changes.

Diagnostics

The remote browser channel currently returns values including:

Captures run in agent capture mode: selection contours, gizmos, grids, and measurement overlays are hidden during the capture (and restored afterwards), and every view — including default — uses a deterministic camera preset, so screenshots do not depend on where the user last left the orbit.

Diagnostics complement the image; they do not replace visual inspection. Read the geometry findings first, then confirm them in the views: they are approximate evidence, not verdicts.

Client visual checklist

The agent should inspect every image:

1. Does the silhouette match the request?
2. Are all required major assemblies present?
3. Are scale and proportions plausible?
4. Do components meet at their intended interfaces?
5. Are unintended collisions or duplicate geometries visible?
6. Are any parts floating or far outside the model?
7. Are visible patterns, spacing, and parameters consistent?
8. Do the browser or scene report errors?

The client must not report “visually verified” until the final render is complete, every image is visibly presented in Codex/Claude, and concrete feedback is given per view.

If no screenshot returns

Check in this order:

1. Re-run confbuild_prepare_browser and perform its action: is the exact requested revision connected?
2. Are the browser and MCP connected to the same confBuild account?
3. Has the 3D scene fully loaded?
4. Does the tab remain open and active enough to render canvas frames?
5. Is the client polling the same job instead of repeatedly creating new ones?

After the timeout, the server returns RENDER_FAILED instead of accessing another tab or user.

Multiple open tabs

If multiple matching tabs are open, a transactional claim lease selects exactly one for the job. Other projects/configurations and dirty stale tabs are never overwritten by the handoff logic.

Local developer mode

The local STDIO server additionally supports auto, headed, headless, and an explicitly exposed attached mode through CONFBUILD_MCP_CDP_URL. These Playwright/CDP modes are development and CI features; customers using the hosted MCP use the browser-tab channel.

Next step

Render-tool arguments are listed in the tool reference. For failures, see security & troubleshooting.