Set up MCP

Quickstart

Run the following commands from the root of the confBuild repository:

nvm use
npm run mcp:confbuild:install
npm run mcp:confbuild:test

This installs only the local MCP package dependencies and runs its prompt, unit, and protocol checks. You do not need to rebuild the confBuild web client.

1. Check the requirements

The server runs locally as a Node process. It does not require its own language-model API key.

2. Configure confBuild authentication

The existing macOS Keychain integration is recommended. First check whether authentication already works:

npm run playwright:confbuild:check-login

If the stored password is missing or expired, refresh it:

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

The MCP server uses credentials in this order:

1. CONFBUILD_FIREBASE_CUSTOM_TOKEN
2. CONFBUILD_EMAIL and CONFBUILD_PASSWORD
3. macOS Keychain service codex-confbuild-playwright

Credentials are never returned to the MCP client. confbuild_auth_status reports only the user ID, email address, and credential source.

3. Connect Codex

The repository already contains a project-scoped .codex/config.toml:

[mcp_servers.confbuild]
command = "node"
args = ["tools/confbuild-mcp/server.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Open Codex at the repository root or reload the project. The confbuild server should then expose its tools, resources, and the confbuild-design prompt.

The project also includes the $confbuild-mcp-agent skill for the complete agent loop. A natural request such as “Create a house through the confBuild MCP” is enough for a compatible Codex client to select the workflow.

4. Connect Claude Code

Claude Code reads the included .mcp.json:

{
  "mcpServers": {
    "confbuild": {
      "command": "node",
      "args": ["tools/confbuild-mcp/server.mjs"],
      "env": {}
    }
  }
}

Open Claude Code at the repository root, approve the project-scoped MCP server if prompted, then restart or reload the session.

5. Connect another MCP client

Another local client needs an STDIO server definition with:

• Command: node
• Arguments: tools/confbuild-mcp/server.mjs
• Working directory: confBuild repository root
• Environment: only the required confBuild or browser variables

Use an absolute server path if your client does not set the working directory reliably.

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/sheetbuild2/tools/confbuild-mcp/server.mjs"]
}

6. Choose a browser mode

With no extra configuration, browserMode: auto first uses an explicitly attached browser if CONFBUILD_MCP_CDP_URL is set. Otherwise, the server launches a visible persistent Chromium browser and falls back to headless mode if that launch fails.

For security, the server cannot silently take over a normally opened Chrome tab. attached mode works only with a deliberately exposed CDP endpoint. See the browser and screenshot loop for details.

7. Test the connection

First ask the client for a read-only status check:

Use the confBuild MCP to check authentication status and available browser modes.
Do not change any project.

Then try a small private project:

Use the confBuild MCP to create a private project containing a red 100 mm cube.
Validate, render, and visually inspect the result.

The client should start with confbuild_start_design_session, provide an editable project link at the end, and leave no uncommitted changes behind.

Update after prompt changes

When the prompt editor’s master prompts change, refresh and verify the reproducible MCP artifacts with:

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

Prompt hashes prevent a client from silently using stale exports.

Next step

Continue with the agentic project workflow. For authentication, browser, or revision failures, see security & troubleshooting.