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, or generic
• promptDetail: normally essential

The response contains the design session, matching prompt bundle, browser capabilities, and recommended next tool. This step matters because it also delivers the current prompt-editor master prompts to the client.

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.

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 working copy inside the MCP process. 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;
• row, cell, output, and payload counts.

confbuild_commit_edit then saves atomically. 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.

6. Start and poll a render job

confbuild_render_project starts asynchronously. The client polls confbuild_get_render_result until the status is completed. It then receives up to four PNG images plus browser and scene diagnostics.

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 inspects every image and evaluates the diagnostics. 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?
• 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 local session state with confbuild_finish_design_session. Uncommitted changes or an unfinished final render prevent completion.

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

You can watch the project in a visible browser while the agent works. Keep in mind:

• The managed headed browser uses its own persistent profile by default.
• The exact already-open user window is used only in explicitly configured attached mode.
• 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 promptDetail: essential unless a specialized rule is missing.
• 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.