Install and set up confBuild MCP

Fastest setup

One link. Your AI handles the setup.

Paste this page's URL into Claude Code or Codex and send:

“Set up confBuild MCP for me using this page: https://confbuild.com/en/docs/confbuild-mcp-setup/”

The AI follows the current instructions and tells you when to approve OAuth. No repository, Node.js, API token, or manual skill copying.

Show the complete installation guide Plugin commands, OAuth, manual MCP setup, browser loop, updates, and developer mode

One-click package: MCP and skill together

The recommended customer path is the confBuild plugin. This single installable package configures every related component:

  • the OAuth-protected Remote MCP connection to https://app.confbuild.com/mcp;
  • the confbuild-mcp-agent skill with the complete modeling and screenshot workflow;
  • the required metadata for Codex/ChatGPT and Claude Code.

The public beta package is available now through the self-hosted confBuild marketplace. Choose your client and run its two commands.

Claude Code

claude plugin marketplace add doczoidberg/confbuild-plugins
claude plugin install confbuild@confbuild

Run /reload-plugins, open /mcp, and approve confBuild OAuth if requested. Then invoke /confbuild:confbuild-mcp-agent.

ChatGPT and Codex

codex plugin marketplace add doczoidberg/confbuild-plugins
codex plugin add confbuild@confbuild

Restart an already-open client, use /skills to confirm that confBuild MCP Agent appears, and invoke $confbuild-mcp-agent.

The package includes a Codex SessionStart hook that checks the self-hosted confBuild marketplace at most once every 24 hours. Review and trust the hook once when Codex asks. New marketplace versions are then downloaded automatically. When Codex reports that it found an update, start a new task so its skill and MCP package are guaranteed to come from the refreshed version.

Installations older than this auto-updater need one final manual codex plugin marketplace upgrade confbuild to receive the hook. The same command remains the manual fallback if the automatic check cannot run.

The package source, manifests, skill, and MCP endpoint are reviewable in the public confBuild plugin repository on GitHub.

No repository checkout, Node.js/npm, API token, or manual skill copying is required. Installing the plugin brings both the MCP connection and its operating instructions into the client.

Distribution status: the plugin is publicly available as a self-hosted beta marketplace. Reviews for the OpenAI universal Plugins Directory and Anthropic community marketplace remain separate and are still pending. The manual MCP-only path below remains available for clients that cannot install plugins.

Update the Claude Code plugin

Claude Code caches marketplace plugins by version. Refresh the marketplace first, then update the plugin in the scope where it is installed:

claude plugin list --json
claude plugin marketplace update confbuild
claude plugin update confbuild@confbuild --scope user

The normal customer installation uses user scope. If claude plugin list --json reports project or local, pass that scope instead. In an open Claude Code session, run /reload-plugins after installation or update; a new session is not required. Open /mcp to confirm that the hosted server is connected and complete OAuth if requested.

The plugin already registers https://app.confbuild.com/mcp. Do not add the same hosted connection manually as well. Claude gives local and project MCP configurations precedence over user and plugin servers. If claude mcp list reports conflicting scopes, remove an obsolete manual entry or rename a repository-only STDIO server to a distinct name such as confbuild-local, then run /reload-plugins again.

Manual MCP-only fallback

For the current manual test path, use this address in your MCP client:

https://app.confbuild.com/mcp

This is a hosted Streamable HTTP MCP. Customers need:

  • a normal confBuild account;
  • Codex, Claude, or another client with remote MCP and OAuth support;
  • a browser for sign-in, consent, and the screenshot loop.

You do not need a local repository, Node.js, npm, NuGet, a confBuild API key, or your own MCP server.

1. Add the remote MCP to your client manually

Open your client’s MCP server or connector settings and add a remote/HTTP server:

Field Value
Name confBuild
URL https://app.confbuild.com/mcp
Transport Streamable HTTP / Remote MCP
Authentication OAuth, handled automatically by the client

Exact menu labels depend on the client. Do not configure a local node command and do not put a password or API token in the MCP configuration.

2. Approve access in confBuild

On the first connection, the client discovers the OAuth endpoints automatically and opens the confBuild consent page.

  1. Sign in to app.confbuild.com with the intended confBuild account.
  2. Check the MCP client shown on the consent page.
  3. Choose Allow access.
  4. Return to the MCP client.

Consent binds every private project, session, and render operation to that account’s Firebase user ID. It does not give confBuild access to your Codex or Claude account.

3. Distinguish the skill from the MCP prompt

Entering an MCP URL directly does not install a skill in Codex or Claude Code. The tools and MCP prompt work, but $confbuild-mcp-agent does not automatically appear under /skills.

The complete customer setup is therefore the installable package described above. Manually adding the MCP URL is an MCP-only compatibility path. Use the dynamically delivered confbuild-design MCP prompt there. In Claude Code, an MCP prompt appears as a slash command in the form /mcp__SERVERNAME__PROMPTNAME.

After the plugin is installed, start a new task or reload plugins in Claude Code. In Codex, use /skills to confirm that confBuild MCP Agent appears, then test it with $confbuild-mcp-agent; in Claude Code the plugin skill is /confbuild:confbuild-mcp-agent. If the skill is missing despite an installed plugin, check that the plugin is enabled; disconnecting and reconnecting the MCP URL alone cannot install it.

4. Check the connection

Start with a read-only request:

Use the confBuild MCP to check authentication, available prompts, and browser
render capability. Do not change any project.

A successful v0.17 direct connection exposes 35 tools, 49 resources, the confbuild-design prompt, and one server-side skill catalog entry for plugin-import scans. The installable skill itself comes from the plugin. The client first calls confbuild_start_design_session, loads the required context, and then explicitly plans Main Part plus functional subsheets through confbuild_plan_sheet_topology before mutating a project.

5. Create a first project

With the plugin installed:

Use $confbuild-mcp-agent and the confBuild MCP to create a private project
containing a red 100 mm cube. Validate, save, render, and visually inspect it.

With the direct MCP-only connection, submit the same request through the confbuild-design MCP prompt.

The client should return an editable link such as https://app.confbuild.com/e/PROJECT_ID.

6. Enable the screenshot loop

Browser connection is a prerequisite for creation, cloning, editing, commit/restore, rendering, and export. Before a new project exists, the client calls confbuild_prepare_browser with the design session: any signed-in confBuild tab is enough, or it opens the dashboard when no tab exists. After the project exists, it repeats the call with waitMs until connected: true proves the exact revision. It reuses an exact tab, reloads a clean stale tab, or navigates a dashboard. It opens a new tab when another project/configuration or unsaved local work must be preserved. Existing browser work is never overwritten.

No browser extension or remote debugging is required. The tab must:

  • be signed in with the same confBuild account;
  • have the requested project and confirmed revision open;
  • be fully loaded and remain open during the render job.

The browser tab is the default renderer. Server rendering is used only when you explicitly request it; the client then sends rendererMode: server-headless and serverRenderingExplicitlyRequested: true. The exact browser connection remains mandatory in that mode too.

See the browser and screenshot loop for details.

Continue an existing project

You can put a private project ID or complete confBuild link directly in your request:

Continue editing https://app.confbuild.com/e/PROJECT_ID.
Change only the roof and preserve the windows and floors.
Save, render, and visually inspect the result.

Owned private projects are edited directly. Public or read-only projects are cloned into the user’s private workspace first.

Local developer mode

The local STDIO server remains available for confBuild developers and repository automation. Only this mode requires the repository and Node.js 22.22.3:

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

Local Codex or Claude project configuration can start tools/confbuild-mcp/server.mjs. Name a Claude developer entry confbuild-local, not confbuild, so it cannot shadow the hosted customer plugin. This developer workflow is not the customer installation path.

Next step

Continue with the agentic project workflow. For OAuth, project, or rendering failures, see security & troubleshooting.

Back to Documentation