MCP tool & Sheet reference

Server surface

Hosted version 0.4 exposes 20 tools, one reusable prompt, one skill catalog entry for plugin-import scans, and 28 resources at https://app.confbuild.com/mcp. The catalog does not install a skill for a direct MCP connection; confbuild-mcp-agent is bundled with the confBuild plugin. Transport is Streamable HTTP with OAuth/PKCE. Structured results are returned as MCP text and structuredContent, with screenshots additionally returned as native image blocks. The local STDIO transport exposes the same functional surface for developers.

The reusable prompt is named confbuild-design. It instructs the client to call confbuild_start_design_session first and follow the complete create/edit/render loop.

The server advertises io.modelcontextprotocol/skills. skills/list and skills/get return the complete skill with its resource manifest and SHA-256 digests; resources/read returns every declared file. Under the current OpenAI contract, Scan Tools uses this interface for a static plugin import, not for runtime installation in a connected client. Direct MCP connections use the confbuild-design prompt as the compatible entry point.

Tools by phase

Orientation and prompts

Important confbuild_start_design_session inputs:

{
  "request": "Complete user request",
  "projectReference": "optional ID or URL",
  "client": "codex",
  "model": "exact public model ID when known",
  "profile": "machine",
  "promptDetail": "essential",
  "knownBundleHashes": ["sha256 of a bundle you already hold"]
}

Classify the domain yourself and pass an explicit profile (building, machine, 3dprint, generic); auto only triggers a keyword fallback for clients that cannot classify. knownBundleHashes is optional: when it contains the returned bundleSha256, the bundle comes back without its text (bundleTextOmitted: true), which removes the largest repeated payload from follow-up sessions.

Access and projects

confbuild_create_project and confbuild_clone_project support an idempotencyKey. Reusing the same key in the same user account resolves to the same deterministic project ID.

model is optional. The client should report only its exact public model ID and omit the field otherwise; the server never guesses a model. Pass designSessionId into create, clone, and begin edit.

The request value passed to confbuild_start_design_session is stored verbatim in the admin-only MCP history. Clients must put only the actual user request there, never private reasoning, screenshot analysis, or credentials. After successful commits, the server additionally stores the latest Sheet state; intermediate patches are not archived as history entries.

Separately, the server maintains content-free usage statistics: tool, time, user/client ID, optional reported model on the start event, status/error code, duration, bytes, Sheet/row/cell quantities, commits, project actions, and render activity. Prompt text, cell values, images, and reasoning are never copied into this telemetry. Model tokens consumed by the MCP client are technically invisible to the server.

MCP-created and MCP-edited projects receive a compact metadata.agentMcp provenance marker: created/edited, timestamps/count, client/tool, optional reported model, profile, and MCP client name/version. The admin area shows these fields in “MCP History” and “Recent user work”; the marker contains no prompts, Sheet values, screenshots, responses, or reasoning.

confbuild_read_project can limit context:

{
  "reference": "PROJECT_ID",
  "sheetNames": ["Main Part", "Frame"],
  "maxRowsPerSheet": 500
}

If truncated: true is returned, the client must not replace that complete Sheet until it has read the untruncated content.

Editing and persistence

Always pass the designSessionId returned by confbuild_start_design_session to confbuild_create_project, confbuild_clone_project, and confbuild_begin_edit. This keeps attribution, the user request, and committed Sheets associated with the correct history entry when multiple agents run concurrently.

confbuild_commit_edit can also update project fields:

{
  "editSessionId": "edit-…",
  "mutationId": "stable-client-mutation-42",
  "projectPatch": {
    "name": "Portal Mill 800",
    "projectType": "machine-component",
    "description": "Parametric portal milling machine",
    "metadata": { "source": "mcp-client" }
  }
}

Each commit stores the pre-commit workbook as a rollback snapshot (preCommitSnapshotId in the result); pass "snapshot": false to opt out. Retention keeps the newest snapshots per project and prunes older ones automatically. A restore commits the snapshot as a regular new revision, so it is itself undoable and never bypasses revision protection.

Browser and visual loop

confbuild_get_render_result supports includeImages: false when the client initially needs only status or diagnostics. maxImages can be 1–4.

waitMs (0–30,000) turns the poll into a server-side long-poll: the call waits in place until the job completes or the wait elapses, instead of forcing rapid client polling. While a hosted job is still unclaimed, the response reports how long it has been pending and — after a few seconds — an explicit hint that no signed-in editor tab with the target project open has picked it up.

Completed results include two additional evidence blocks:

• diagnostics.geometry: an approximate geometry audit with BVH-confirmed collision pairs, AABB-suspected overlaps, detached parts that touch nothing, far outliers, and model bounds. Findings are advisory and map onto the model-loop defect categories; the client verifies them against the returned views.
• iterationDelta: mesh/output/collision/detachment/bounds deltas against the previous completed render of the same project, so “did my patch change anything” does not need a screenshot comparison.

Completion

Completion fails while the edit session contains uncommitted changes or the specified final render job is incomplete.

The finish call accepts a structured, content-free outcome: completionState (complete/partial/blocked), iterationsUsed, and fixedDefectCategories/residualDefectCategories restricted to the model-loop defect enum. Only these enums and counts are stored for loop-quality trends; the free-text summary is returned to the client and never persisted.

Workbook format

A workbook is an array of Sheet objects:

[
  {
    "name": "Main Part",
    "visible": true,
    "data": [
      ["INPUTID", "TYP", "VALUE", "VALIDATED", "UNIT", "LABEL", "VISIBLE", "MIN", "MAX", "PARAMS", "ONCLICK", "ONCHANGE"],
      ["width", "slider", 1000, true, "mm", "Width", true, 500, 2000, "", "", ""],
      ["OUTPUTID"],
      ["#", "type", "width", "height", "depth", "material", "x", "y", "z", "rx", "ry", "rz"],
      ["body", "cube", "=C2", 600, 400, "#8C30F5", 0, 0, 0, 0, 0, 0]
    ]
  }
]

The complete columns and geometry rules come from the prompt bundle. Resource confbuild://schema/workbook describes the compact MCP format.

Patch operations

Indexing

• sheetIndex is zero-based.
• row, numeric column, startRow, and A1 addresses are one-based.
• Columns may be numbers or letters.

Set cells

{
  "editSessionId": "edit-…",
  "operations": [
    {
      "op": "set_cells",
      "sheetName": "Main Part",
      "cells": [
        { "a1": "C2", "value": 1200 },
        { "row": 2, "column": "F", "value": "Width" }
      ]
    }
  ]
}

Add or replace a Sheet

{
  "op": "upsert_sheet",
  "sheet": {
    "name": "Frame",
    "visible": true,
    "data": [["INPUTID"], ["OUTPUTID"]]
  }
}

Validation

Validation returns valid, errors, warnings, and statistics. Hard errors include:

• empty workbook;
• empty or duplicate Sheet names;
• rows that are not arrays;
• unserializable values or non-finite numbers;
• more than 2,000,000 cells.

Warnings include a missing INPUTID header, missing OUTPUTID marker, or duplicate output IDs. A deterministic engine-trap lint additionally flags mistakes that would otherwise surface only as a wrong render: a bare cell reference such as D4 where =D4 was meant (NAKED_CELL_REFERENCE), text in numeric columns that the engine silently coerces to 0 (NON_NUMERIC_VALUE), two consecutive # header rows of which only the last takes effect (CONSECUTIVE_HEADER_ROWS), data cells beyond the governing header (ROW_WIDER_THAN_HEADER), and output rows without any header (MISSING_OBJECT_HEADER). VALUE_SHADOWED_BY_CONFIGMODEL warns when a saved editor configuration overrides a patched VALUE cell, so the render shows the saved value rather than the patch. A workbook may be formally saved despite warnings; the client must evaluate them professionally.

Persistence and large Sheets

Small workbooks are stored inline in the project. Above approximately 700 KB of serialized Sheet data, the server automatically uses generation-specific chunks of approximately 240 KB. The manifest and new chunks are written atomically; stale project-Sheet chunks are cleaned afterward.

The client does not manage this storage. On read, the server hydrates both variants into the same workbook format.

State lifetime

In Remote mode, design, edit, and render state is separated by UID and stored in compressed private Cloud Storage. It therefore survives stateless Function instances and becomes invalid after expiry. Local STDIO keeps temporary state only in process memory. Committed projects remain persistent in both modes.

See also

• Agentic project workflow
• Master prompts & AI boundary
• Security & troubleshooting