MCP security & troubleshooting

Security model

The local server is designed to have no more permissions than the authenticated confBuild user.

  • It uses normal Firebase user authentication, not an Admin SDK bypass.
  • Private projects are read and written only in the authenticated user’s path.
  • A bare project ID is looked up in the current user’s private workspace first and the public collection second.
  • Public or read-only projects are cloned privately before editing.
  • The server never returns passwords, custom tokens, or Keychain contents to the MCP client.
  • Writes use revision protection against silent concurrent overwrites.
  • The server does not call AI-provider or confBuild-AI endpoints.

Which tools actually write

Remote write operations are:

  • confbuild_create_project
  • confbuild_clone_project
  • confbuild_begin_edit when it automatically clones a read-only project
  • confbuild_commit_edit

confbuild_apply_sheet_patch changes only in-memory state. confbuild_discard_edit discards only that local working copy and does not delete an already persisted project.

Protect credentials

Prefer macOS Keychain over permanently configured plaintext environment variables. Never include passwords in user prompts, MCP tool arguments, project metadata, or repository files.

npm run playwright:confbuild:check-login

The status result may contain user ID, email, and credential source, but no secret.

Browser and CDP security

Default headed mode uses a separate persistent profile. attached is more powerful: a CDP endpoint can expose tabs and session state.

  • Enable remote debugging deliberately and only for the required session.
  • Bind it to 127.0.0.1, not a public interface.
  • Use a separate browser profile without unnecessary accounts or tabs.
  • Do not share the CDP URL with untrusted clients.
  • Close the debug browser when the work is complete.

The MCP server does not start remote debugging itself and does not close an attached user browser when the process exits.

Common failures

“Unable to authenticate the confBuild MCP server”

Cause: No valid password/token, expired login, or wrong email.

Fix:

npm run playwright:confbuild:check-login
CONFBUILD_EMAIL='your-account@example.com' \
CONFBUILD_PASSWORD='…' \
npm run playwright:confbuild:save-password

Restart the MCP client so the server process reads the refreshed environment or Keychain entry.

“No accessible confBuild project was found”

Cause: Wrong ID, unsupported URL, project is not public, or it is not in the current account.

Fix: Check the ID and use an allowed confBuild URL containing /e/, /editor/, /p/, or /lib/. The server cannot guess or open another user’s private project by ID; publish/share it or copy it into your account.

“The project is read-only”

Cause: The client disabled automatic cloning.

Fix: Call confbuild_begin_edit with cloneReadOnly: true, or call confbuild_clone_project first. The source remains unchanged.

REVISION_CONFLICT

Cause: The project was saved in the browser or by another agent after the edit session began.

Fix:

  1. Re-read the current project.
  2. Compare the base and current versions.
  3. Deliberately apply the intended local changes to the new version.
  4. Validate and commit again.

There is intentionally no force-overwrite switch.

“Validation failed”

Cause: At least one hard workbook error, such as duplicate Sheet names, an unserializable cell, or a size limit.

Fix: Read confbuild_validate_edit, correct every entry under errors, and validate again. Warnings do not automatically block a commit, but should be evaluated before saving.

“Commit the dirty edit before rendering”

Cause: The browser and Firebase would still see the previous revision.

Fix: Validate and commit the edit. If you want to abandon it, use confbuild_discard_edit and render the persisted project.

Render job remains running

Cause: The editor is still loading, authentication is waiting, render jobs run serially, or the project is large.

Fix: Continue polling confbuild_get_render_result without starting a duplicate job. The job eventually fails after its configured timeout. Then check authentication, browser mode, and whether the project URL loads in the visible browser.

RENDER_FAILED or browser timeout

Cause: Chromium is missing, login redirect, editor does not load, CDP endpoint is absent, or a UI selector changed.

Fix:

  1. Check confbuild_browser_capabilities.
  2. For attached, verify CONFBUILD_MCP_CDP_URL and the local browser.
  3. Try browserMode: headed and watch the browser.
  4. Try browserMode: headless for unattended checks.
  5. Open the project manually and fix visible editor errors.

No images in the result

Cause: includeImages: false, maxImages too small, or the job is not complete.

Fix: After completed, call confbuild_get_render_result again with includeImages: true and the desired maxImages.

Prompt test reports stale artifacts

Cause: Prompt-editor sources changed without refreshing MCP exports.

Fix:

npm run mcp:confbuild:prompts
npm run mcp:confbuild:test

Generated prompt artifacts and their source changes belong in the same change set.

Session is missing or expired

Cause: The MCP process restarted or the in-memory session was inactive for more than six hours.

Fix: Start a new design/edit session from the last committed project. Uncommitted in-memory patches cannot be recovered; committed changes remain intact.

Large Sheets or missing chunks

Cause: A chunked project is incomplete or exceeds safety limits.

Fix: Do not bypass the error by manually editing the manifest. Re-save the project from a complete version or clone it from a complete original/backup. MCP limits are 2,000,000 cells and 450 chunks per commit.

Known limits of local version 0.1

  • STDIO targets a local machine and local client, not an arbitrary remote SaaS client.
  • Sessions and render jobs are not persistent or transferable between clients.
  • Structural validation is not a complete collision, manufacturing, building-code, or solver certificate.
  • Browser capture and orbit presets partly depend on the current editor UI.
  • There is no automatic project snapshot/rollback before each MCP commit yet.
  • The MCP server is coupled directly to the current Firestore/chunk schema.
  1. Remote access: Authenticated Streamable HTTP with OAuth for Skedio or other SaaS clients.
  2. Browser bridge: Signed extension or native-messaging bridge to select the exact user tab safely.
  3. Shared schema package: Identical Sheet types, serialization, and validation for Angular and MCP.
  4. Persistent agent runs: Local database or Firestore trace for resume, audit, and client handoff.
  5. CAD quality gates: BVH collision classes, bounding outliers, disconnected components, missing metadata, and domain rules.
  6. Versions/rollback: Project snapshot before commit and an explicit restore tool.
  7. Stable cameras: Editor-native camera presets and a UI-free agent capture mode.

Security checklist before production use

  • Use a separate, appropriately permissioned confBuild user account
  • Keep secrets in Keychain or short-lived environment variables
  • Clone public templates instead of modifying originals
  • Rebase revision conflicts; never bypass them
  • Review the final screenshot and diagnostic report
  • Obtain human approval for safety, structural, standards, and manufacturing assumptions
  • Open CDP locally and only for the required duration
  • Add OAuth, tenant isolation, quotas, and audit before remote use

More help

For setup problems, start with set up MCP. For tool arguments and patch formats, see the MCP tool & Sheet reference.

Back to Documentation