Browser & screenshot loop

The client sees the real confBuild result

In hosted Remote MCP mode, neither the AI nor a browser in the MCP backend renders the scene. The user’s already signed-in confBuild tab captures it:

  1. The MCP client saves the intended project revision.
  2. The user opens the project link in app.confbuild.com in parallel.
  3. confbuild_render_project creates a private render job for that user and project ID.
  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 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.

Privacy boundary: the web client listens only below its own Firebase UID. Screenshots are private under mcp-renders/<uid>/<jobId> and are returned as MCP image content to the authorized client.

Asynchronous render sequence

The flow uses two tools so a slow project does not block one long tool call:

  1. confbuild_render_project starts the job and returns a renderJobId.
  2. confbuild_get_render_result is polled until the job is completed or failed. Pass waitMs (up to 30,000) to long-poll: the server waits in place instead of requiring rapid client polling, and while the job is unclaimed it reports how long it has been pending plus a hint when no signed-in editor tab with the project open has picked it up.

Example:

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

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

Returned views

Up to four PNGs are available:

  • default: current editor 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, Claude, or another MCP client preserve their aspect ratio and are limited to 960 × 640 pixels. The response also carries preview and original dimensions. This keeps frequent multi-view checks useful while substantially reducing image payload and cloud transfer.

Visible MCP status in the editor

Once an OAuth MCP client is authorized for the signed-in account, the editor shows a compact MCP badge. It distinguishes ready, active, waiting for the 3D view, capturing preview, sending preview, sent, and failed. With multiple authorized clients, the badge names the most recently active client. It remains hidden when there is no valid authorization or matching render job.

Diagnostics

The remote browser channel currently returns values including:

Field Meaning
meshCount / visibleMeshCount Total and visible Three.js mesh counts
uniqueOutputIds Number of detected unique confBuild outputs
page.url / page.title Project page that was actually captured
canvasWidth / canvasHeight Captured canvas resolution
width / height Resolution of the returned, reduced preview
originalWidth / originalHeight Original canvas resolution before reduction
browserErrors Errors reported by the browser channel
geometry Approximate geometry audit: BVH-confirmed collision pairs, AABB-suspected overlaps, detached parts, outliers, and model bounds
iterationDelta Mesh/output/collision/detachment/bounds deltas against the previous completed render of the same project

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 and every returned image has actually been inspected.

If no screenshot returns

Check in this order:

  1. Is the exact requested project open in the browser?
  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 the same project is open in multiple tabs, more than one tab may notice the job. Upload paths and job status are idempotent, but one open target tab is recommended for a stable flow. A future tab lease should select exactly one tab.

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.

Back to Documentation