Install the builder

How a developer installs the mdlake builder plugin in Claude Code, connects a site folder to a workspace with MDLAKE_API_URL and MDLAKE_TOKEN, checks that the lake tools work, and keeps the plugin up to date.

The builder is a plugin for Claude Code. It gives Claude the skills, rules and template to generate a site from a lake. This page is for developers. You install the plugin once on your machine, then connect each site folder to its workspace with two lines in a .env file.

Before you start

Claude Code is installed and you can start it in a terminal with claude. Follow Anthropic’s own installation instructions for your system.
Node.js 22.23.4 or newer. The site template and the kit declare this version as the minimum. Check with node --version.
Git is installed, and you can sign in to GitHub from the command line. Builds fetch the lake from Git with your own sign-in. A credential helper, such as Git Credential Manager or gh auth login, does this.
A running CMS with a workspace that has published documents (Install the CMS), and, for the best results, the lake mirrored to GitHub (Connect GitHub).
An admin has made a token for you (Workspace tokens). You can start without one, but the lake tools in Claude Code need it.

Install the plugin

The plugin comes from the mdlake repository, which is also a Claude Code marketplace. The plugin is self-contained: it carries the template, the ruleset, the scripts and the packed @mdlake/lake-loader and @mdlake/site-kit packages, so Claude needs no path to the repository.

Make a folder for the new site and start Claude Code in it:
Bash
```
mkdir my-site
cd my-site
claude
```
PowerShell
```
mkdir my-site
cd my-site
claude
```
Add the marketplace from GitHub:
```
/plugin marketplace add Floydan/mdlake
```
The repository is private, so Claude Code clones it with your own Git credentials. Be signed in to an account that can read Floydan/mdlake (gh auth login, or a credential helper such as Git Credential Manager). git ls-remote https://github.com/Floydan/mdlake.git must work in the same shell. The setup guide in Workspace settings, under AI and API access, shows a line for your installation, with a copy button. Its address comes from the setting Tokens:BuilderMarketplace, which is https://github.com/Floydan/mdlake by default.

To work on the kit itself, add a clone of the repository instead: /plugin marketplace add C:\Projects\mdlake. A marketplace added from a local path is read in place. Do not add the marketplace mdlake from both places at once.
Install the plugin:
```
/plugin install mdlake-builder@mdlake
```
Claude Code shows the plugin’s details and asks for a scope. Choose user scope to have the plugin in every folder. You can also run both steps from a shell with claude plugin marketplace add Floydan/mdlake and claude plugin install mdlake-builder@mdlake.
Check that it is there. Type /mdlake-builder: and the skills appear in the list: check-lake, plan-site, scaffold-site, regenerate, refresh-content, generate-copy, add-page, add-component, add-api-route, add-form, add-backend, setup-hosting, upgrade-ruleset and publish.

Expected result: the skills are listed and /plugin shows mdlake-builder at version 0.19.2 or newer.

To try the plugin without installing it, point Claude Code at the plugin folder of a checkout:

Bash

claude --plugin-dir /path/to/mdlake/builder/plugin

PowerShell

claude --plugin-dir C:\Projects\mdlake\builder\plugin

What the plugin contains

Part	What it does
Skills	Guided workflows. They show as `/mdlake-builder:<skill>`. They stop and ask for your approval at the points that matter, such as the plan and the design. See Skills.
Ruleset	The agency’s conventions. Scaffolding copies it into the site as `CLAUDE.md`.
Template and kit	The starting point of a site and the engine behind it. The site keeps its own config, theme and content. The engine is `@mdlake/site-kit`.
Hook: locked files	Blocks Claude’s edits to files that the tools own. See Ownership zones.
Hook: session start	Prints one line when the site’s ruleset is behind the installed plugin.
Hooks: usage reporting	Report AI token counts to the CMS when the site has a token with Can report AI usage. Counts only, never prompts, answers or files.
`lake` MCP bridge	Lets Claude look at the lake through the CMS.

Connect the site to the CMS

The bridge reads two settings from the .env file of the site folder Claude Code runs in. Each site therefore talks to its own workspace with its own token.

In the site folder, create a file named .env with two lines:
```
MDLAKE_API_URL=https://cms.example.com/api/lake/acme
MDLAKE_TOKEN=mdl_abcd1234_the-secret-you-copied
```
The address is the CMS address, then /api/lake/, then the workspace’s short name. Workspace settings shows it with the real values in the second line of the guide 1. Claude Code with the mdlake builder. Locally it looks like http://localhost:5080/api/lake/mdlake-demo (the API is published on port 5080 by docker-compose.yml).
Make sure .env is not committed. Scaffolded sites ignore it already. For a folder that is not scaffolded yet, add .env to .gitignore yourself.
Quit Claude Code and start it again in the site folder:
Bash
```
claude
```
PowerShell
```
claude
```
Type /mcp. The server lake is listed.

Expected result: Claude can call the CMS tools lake_info, lake_manifest, search_documents, get_document, document_shape, query_collection, list_assets and get_asset. Ask “What workspace are you connected to?” and Claude answers from lake_info.

If the settings are missing, wrong or refused by the CMS, the bridge offers one tool, lake_connect_help, and no error. The skills then read the local lake clone instead.

Warning

The token in .env is a secret. Never commit it, paste it into a chat or put it in a build log. If it leaks, revoke it (Workspace tokens).

The MCP is for looking, the clone is for building

The MCP bridge helps Claude find material faster. It is never the source of a build. A site builds from the lake clone in .mdlake/lake, which the kit fetches from Git at exactly the commit in lake.lock. If the MCP shows a document that the clone does not have, it was published after the locked commit and is not part of the site until you run refresh-content. See How sites work.

AI usage reporting

When the token has Can report AI usage, the plugin reports how many AI tokens your Claude Code sessions used to the workspace. The CMS shows the sum under AI usage, so a client can be billed.

It sends counts per model and per skill, for example plan-site. It sends no prompts, answers or files.
It reports at the end of a session, and after turns of long sessions.
A token without the permission is told so once and nothing is lost: the counts wait in a queue until you use another token.
To see what was reported and what waits, run npx mdlake usage. To send the queue now, run npx mdlake usage --flush. These run inside a site that has the kit installed.
To turn reporting off, set MDLAKE_USAGE_REPORT=0 in .env or in the environment.
A slow or absent CMS never blocks Claude Code. Requests time out after 3 seconds and are retried at the next run.

The lake, on your machine

A site needs the lake itself, not only the MCP. For a site with a remote in lake.lock, the kit fetches the locked commit into .mdlake/lake for you. That folder is ignored by Git. Fetching uses your own Git sign-in, so git ls-remote <clone address> must work from your terminal. The skill check-lake asks the CMS where the mirror is and asks you to confirm it once. Plan a site starts there.

Update the plugin

Installed plugins only update when the plugin’s version changes.

Update the marketplace so Claude Code sees the new version:
```
/plugin marketplace update mdlake
```
Reload the plugins:
```
/reload-plugins
```
In each existing site, run /mdlake-builder:upgrade-ruleset. Claude Code prints one line at the start of a session when a site is behind, for example “This site uses ruleset 0.7.1; the plugin is 0.8.1 (2 versions behind). Run /mdlake-builder:upgrade-ruleset.” Nothing is printed when the site is current.

Claude Code can refresh marketplaces by itself at startup. For a private repository that needs a token in the environment (GITHUB_TOKEN or GH_TOKEN). Without one, update by hand as above.

A marketplace added from a local path is read in place. After a git pull in the repository, run both commands again. See Upgrade and migrate.

If something goes wrong

What you see	What to do
The `mdlake-builder` skills are not listed	Run `/plugin` and check that it is installed and enabled. Run `/reload-plugins`.
`/mcp` does not show `lake`	The plugin is not installed or enabled, or Claude Code was started in another folder. Start it in the site folder.
Only `lake_connect_help` is offered	`.env` has no `MDLAKE_API_URL` or `MDLAKE_TOKEN`, the token is wrong, expired or revoked, or the short name in the address is not the token’s workspace. Fix the file and restart Claude Code. Ask the tool for help, it says which.
Two sites seem to mix up workspaces	Each site reads its own `.env`. Check which folder Claude Code started in. The environment wins over the file, so also check `MDLAKE_API_URL` and `MDLAKE_TOKEN` in your shell.
The kit cannot fetch the lake	`git` is missing, the sign-in is refused, or the commit has not been mirrored yet. See CI, the lake and caches and check Lake repository in Workspace settings.
`npm install` cannot find `../../packages/lake-loader` or `site-kit`	The site points at the monorepo path. Run `node "<plugin folder>\scripts\vendor-packages.mjs" .` in the site folder, and then `npm install` again. `claude plugin list` shows the plugin folder as “Read from”.
Skill output is unreadable JSON when you run the dev server inside Claude Code	Astro detects AI agents and prints JSON log lines. Run `npm run dev` in your own terminal.

What’s next

Check what the workspace has and plan the site: Plan a site.
Understand the model first: How sites work.