Agentic project workflow

Define the outcome first

A good request describes not just the object, but also the criteria the client should later verify in the browser.

Goal: Parametric portal milling machine
Dimensions: 800 × 500 × 180 mm working volume
Must include: base frame, gantry, X/Y/Z axes, spindle, cable chains
Parameters: working width, working length, gantry height
Quality: connected parts, plausible scale, no unintended collisions
Output: private editable project and visual review from four views

You do not need to follow this exact format. It helps the client separate requirements, assumptions, and acceptance criteria.

The required sequence

1. Start a design session

The client first calls confbuild_start_design_session with your full request. It may also pass:

• projectReference: project ID or URL
• client: codex, claude, or generic
• profile: auto, building, machine, 3dprint, structure (halls/frames/trusses), furniture, or generic
• promptDetail: normally progressive

The response contains the design session, compact prompt core, browser capabilities, and recommended next tool. For a direct MCP connection, that tool is initially confbuild_get_prompt_sections: the client loads the required profile and then only relevant packs such as geometry, systems, or assembly. It then continues with nextProjectTool.

1a. Plan the sheet topology

Before create, clone, or begin-edit, the client calls confbuild_plan_sheet_topology. single-sheet is reserved for a genuinely indivisible part. Machines, buildings, products, furniture, and structures with independently mounted, reusable, repeated, or co-moving units use composite: Main Part remains the first orchestration sheet, while functionally named children own local geometry, mount datums, and child-specific inputs. Repeated assemblies are modeled once and instantiated through multiple exact SHEET: <name> rows. Project creation immediately seeds every planned named subsheet.

2. Select the target

New projects and clones should receive a stable idempotencyKey. If the client retries the same call after a connection failure, it will not create a duplicate.

2a. Connect the browser

Immediately after session/prompt setup, the client calls confbuild_prepare_browser. For a new design, the design-session call proves any signed-in confBuild tab or opens the dashboard before project creation. For a resolved, created, or cloned target it performs reuse, reload, navigate, or open-new with Chrome/browser control and repeats the call until connected: true proves the exact project, configuration, and revision. A different project/configuration tab and a stale tab with unsaved work are preserved; if no confBuild tab exists, a new tab is opened. The server blocks create, clone, begin-edit, commit, and restore without the applicable proof, and the client repeats exact proof after create/clone and every commit or snapshot restore.

3. Read and plan the workbook

confbuild_begin_edit returns a complete normalized workbook and its base revision. For large existing projects, the client can first use confbuild_read_project to read only relevant Sheet names or a limited number of rows.

When continuing an existing project, the client should:

• preserve stable output IDs and working formulas;
• avoid replacing unchanged Sheets;
• inspect references between Main Part and sub-Sheets;
• fully read any Sheet before replacing it completely.

4. Apply changes locally

confbuild_apply_sheet_patch initially changes only the temporary edit-session working copy. In Remote mode this session is UID-separated and persistent, but the project itself remains unchanged until commit. Supported operations are:

• replace the complete workbook;
• add or replace a Sheet;
• delete, rename, show, or hide a Sheet;
• set individual cells;
• replace, insert, or delete rows.

For a new model, replace_workbook is often appropriate. For an existing project, upsert_sheet, set_cells, and localized row operations are safer.

5. Validate and save

Before every save, the client calls confbuild_validate_edit. Errors must be fixed; warnings must be deliberately evaluated. Checks include:

• unique Sheet names and valid 2D data;
• JSON/Firestore serializability;
• INPUTID and OUTPUTID markers;
• duplicate output IDs;
• conformance with the topology plan: Main Part first, every planned child reachable, no cycles/orphans, and complete parent-to-child parameter columns;
• engine-trap lint: bare cell references without =, text in numeric columns, consecutive # headers, cells beyond the header;
• VALUE cells that a saved editor configuration will override (VALUE_SHADOWED_BY_CONFIGMODEL);
• row, cell, output, and payload counts.

confbuild_publish_checkpoint or confbuild_commit_edit then atomically saves the workbook and project scriptcode. If the user changed the same project in the browser, the server returns REVISION_CONFLICT. The client must re-read the current version and deliberately rebase its edits. Forced overwrites are not supported. Every successful pass also requires a complete pre-commit rollback snapshot; if snapshot creation fails, the saved project remains unchanged. confbuild_list_project_snapshots, confbuild_diff_revisions, and confbuild_restore_project_snapshot trace or undo a regression including source code, and restore snapshots the state it replaces so it is itself undoable.

6. Start and poll a render job

After browser reconfirmation, confbuild_render_and_wait preferably starts and waits in one call; alternatively confbuild_render_project starts asynchronously and the client polls confbuild_get_render_result with waitMs. The browser tab renders by default without automatic server fallback. Only when the user explicitly asks for server rendering does the client set rendererMode: server-headless together with serverRenderingExplicitlyRequested: true; browser connection remains mandatory. The result contains up to seven ordered, captioned PNG images (views default, right, front, left, back, top, bottom) plus browser/scene diagnostics, geometry audit, and iterationDelta. For composite projects, subsheetCount or subprojectCount must prove at least every planned instance.

For multi-part models, the result returns confbuild_inspect_outputs with exact output IDs as the next step. The client inspects all four images — ghosted context, isolation, automatic center section, and x-ray — before diagnosis or repair, and repeats the same set after a change.

Only a persisted revision can be rendered. The server rejects rendering while the edit session has uncommitted changes.

7. Review and iterate

The MCP client reads the machine evidence first — geometry findings (collision pairs, detached parts, outliers) and the iteration delta — then displays every returned image in order in Codex/Claude and gives concrete feedback for each view. If presentation.omittedImageCount reports omitted images, it retrieves them before diagnosis or completion. Typical questions include:

• Is the requested object immediately recognizable?
• Are the overall proportions and units plausible?
• Are assemblies spatially connected?
• Are components, openings, or functional details missing?
• Is any geometry visibly floating, duplicated, or colliding — and does the geometry audit confirm it?
• Did the last patch actually change the scene (iterationDelta), or does the data path need fixing first?
• Do the browser or editor report errors or unresolved references?

If needed, repeat patch → validate → save → render → review. A successful commit alone is not a visual approval.

8. Finish cleanly

The client closes temporary session state with confbuild_finish_design_session, reporting the structured outcome (completionState, iterationsUsed, fixed/residual defect categories) as content-free enums. Uncommitted changes, an unfinished final render, a violated topology plan, or missing nested-scene diagnostics prevent a complete outcome.

The final report should include:

• editable project link;
• key changes and parameters;
• deterministic validation result;
• findings from every screenshot;
• remaining assumptions or professional limitations.

Edit an existing project by ID or URL

Supported examples:

mcp-1234567890abcdef
https://app.confbuild.com/e/mcp-1234567890abcdef
https://app.confbuild.com/editor/mcp-1234567890abcdef
https://app.confbuild.com/p/public123/config-a
https://app.confbuild.com/lib/public123

You can simply tell the client:

Continue editing this project: https://app.confbuild.com/e/PROJECT_ID
Do not replace the complete model. Change only the roof, add 450 mm eaves,
and verify that the windows and floors remain unchanged.

For large projects, explicitly saying what must not change is particularly useful.

Work in the browser at the same time

For the hosted MCP, the client keeps the exact project connected in your normal signed-in browser through confbuild_prepare_browser. Keep in mind:

• The matching confBuild project tab handles remote render jobs by default and uploads private PNGs.
• Dashboard, other project, same/stale revision, and “no tab” are distinguished by the safe handoff matrix.
• The browser and MCP OAuth connection must use the same confBuild account.
• Local headed, headless, and attached modes are relevant only to developers and CI.
• Concurrent manual and MCP saves can cause a revision conflict; this is a safety mechanism.

See the browser and screenshot loop for details.

Keep cost and context small

• Use the default promptDetail: progressive and load only the knowledge packs you need; essential is the monolithic compatibility mode.
• For large projects, read only relevant Sheets—but never truncate one before replacing it completely.
• Prefer localized patches over complete workbooks when only a few regions change.
• Request diagnostics without images when you only need to poll render status.
• Finish completed sessions so the client does not retain unnecessary context objects.

The server itself does not call a model. Token or usage costs come only from the chosen MCP client, plus any normal confBuild/Firebase infrastructure costs.

Next step

Read prompts & the AI boundary to understand automatic master-prompt delivery, or open the tool and Sheet reference for exact operations.