MCP tool & Sheet reference

Server surface

The v0.17 server surface exposes 35 tools, one reusable prompt, one skill catalog entry for plugin-import scans, and 49 resources at https://app.confbuild.com/mcp. New in this release is mandatory Composite-style topology planning for Main Part plus named subsheets. 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.

OAuth access is enforced per tool: mcp covers the protocol and prompt surface, projects:read covers project/session reads, projects:write covers mutations, and render covers render/export jobs and artifact delivery. Starting a render or export requires both projects:read and render; missing authorization returns INSUFFICIENT_SCOPE with the exact missing scopes.

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": "progressive",
  "knownBundleHashes": ["sha256 of a bundle you already hold"],
  "knownSectionHashes": ["sha256 of bundle sections you cached"]
}

Classify the domain yourself and pass an explicit profile (building, machine, 3dprint, structure for halls/frames/trusses, furniture, generic); auto only triggers a keyword fallback for clients that cannot classify. In the default mode, read the compact base, call confbuild_get_prompt_sections with the designSessionId and ids from progressiveLoading.requiredBeforeEditing, and then load only packs the design actually needs. nextProjectTool identifies the project call that follows. knownBundleHashes can omit a cached base completely; knownSectionHashes omits known base, profile, or pack text. essential and full remain available as monolithic compatibility modes.

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 and project scriptcode together as a rollback snapshot (preCommitSnapshotId in the result). Protection is mandatory: the legacy "snapshot": false field remains accepted but is ignored, and snapshot failure leaves the saved project unchanged. Retention keeps the newest snapshots per project and prunes older ones automatically. A restore commits the snapshot as a regular new revision and first snapshots the state it replaces, so rollback is itself undoable. Legacy workbook-only snapshots remain readable and explicitly preserve the current source when restored.

Browser and visual loop

Call confbuild_prepare_browser immediately after session setup. With no project yet, pass the design session: an existing signed-in confBuild tab is reused, otherwise the dashboard is opened before creation. Then call it for the resolved/created/cloned target and again after every commit or restore until connected: true. Exact clean tab ⇒ reuse; clean stale tab ⇒ reload; dashboard ⇒ navigate; another project/configuration, any dirty tab, or no tab ⇒ open-new. Codex/Claude performs the action with host browser control; without browser control, it presents the resource link and waits.

confbuild_get_render_result supports includeImages: false for status-only checks. For visual approval, use includeImages: true with maxImages covering every view. The result interleaves caption and image for Codex/Claude and reports omissions in presentation.omittedImageCount. Render tools also accept captureScope: isolateOutputIds, zoomToOutputIds, ghostOtherObjects, automatic or explicit sectionPlane, and xray. views accepts default, right, front, left, back, top, and bottom.

waitMs (0–120,000; below the client timeout) turns the poll into a server-side long-poll. Browser-tab is the default with no automatic server fallback. rendererMode: "server-headless" is allowed only with serverRenderingExplicitlyRequested: true after the user explicitly requested server rendering; browser connection remains mandatory.

When an export exceeds maxContentBytes, confbuild_get_export_result reports delivery: "chunked", downloadWith: "confbuild_get_export_chunk", and nextOffsetBytes: 0. The client assembles the byte ranges; private Cloud Storage and local filesystem paths are never exposed.

The additional export format names are drawing-pdf, sheetmetal-dxf, cost-json, quote-pdf, purchase-json, purchase-csv, and variant-metrics-json. Drawing pages are fully hydrated before PDF generation; a drawing window opened only for the job is closed without saving. Cost, quote, and purchasing outputs use the application’s canonical BOM and pricing services. Quote and purchasing fail on mixed currencies; quote also fails when required prices are missing. Purchasing lists remain usable when supplier prices are unavailable and report estimated-cost coverage for those lines. No exchange-rate conversion is performed. quote-pdf additionally requires a configured seller identity: a meaningful company or seller name in companyName and either a complete postal contact (street and zipCity) or a valid electronic contact (email, phone, or website). Commercial failures return machine-readable codes such as INVALID_SELLER_IDENTITY, MIXED_CURRENCIES, or MISSING_REQUIRED_PRICES plus PII-free details, for example field names, missing requirements, BOM positions, or currency codes instead of seller or customer data.

Before confbuild_compare_variants, prepare every variant reference separately through confbuild_prepare_browser and keep those tabs open. The comparison rebuilds every saved variant sequentially in the real editor. Saved configurations are pinned to their document path and SHA-256 revision; a missing or changed revision fails only that row. price requires one unambiguous currency and complete coverage, mass requires complete position coverage, co2 defaults to an 80% mass-coverage gate, and bounds metrics are explicit scene-axis measurements.

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.

Since v0.17, confbuild_plan_sheet_topology first declares whether the model is truly one indivisible part or whether Main Part orchestrates named functional child sheets. Composite projects are immediately seeded with the planned subsheets. Validation blocks missing or unplanned children, cycles, wrong parent references, missing child inputs, and empty parameter cells in the parent reference row. Completion additionally requires matching subsheetCount/subprojectCount diagnostics. Formula, SHEET:/PROJECT: resolution, row-type, and input-range checks remain in force. A failed commit returns validation or snapshot errors inline; no new revision is stored without a complete rollback snapshot.

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