Configuration

One thing to configure: where authored tools live on disk. Everything else (sessions, browsers, budgets) runs on verified defaults. Set the root once at startup and every spawned server resolves identically.

Registry root

Resolution order, highest priority first:

--registry DIR flag on mcp serve
AGENT_WEBMCP_REGISTRY env var
Project .agent-webmcp/ found by walking up from the working directory
User-global home (Linux: ~/.local/share/agent-webmcp/registry)

export AGENT_WEBMCP_REGISTRY=$PWD/.agent-webmcp/registryagent-webmcp mcp serve --registry /abs/path/.agent-webmcp/registry

Layout under the root is fixed: <root>/<origin-slug>/<name>/{spec.json,body.js}, plus an origin.txt guard per origin. If two origins ever slug alike, the guard fails loud instead of mixing tools — point the root at a clean dir. Git-track the root (suggested, never automatic).

Prefer one of the explicit two (flag or env) in your harness's MCP server entry. Some harnesses spawn per-call servers with varying working directories, and explicit roots are immune to that.

Environment

Variable	Effect
`AGENT_WEBMCP_REGISTRY`	Registry root (see order above)
`CHROMIUM_PATH`	Chromium binary when none is on
	`PATH` (`chromium`, `google-chrome`,
	`google-chrome-stable` are tried)

That is the whole list. There is no config file: flags plus two env vars cover install-time setup, and the skill (agent-webmcp skill show) covers runtime.

Browser launch

Owned browsers launch headless on a free loopback port with a throwaway profile. Opt-ins per open:

Flag	Effect
`--headed`	Visible window (needs a display; use Xvfb
	headless or drop the flag in CI)
`--cdp <http://host:port>`	Borrow a foreign tab instead
	of launching (the tab gets navigated)

The launch floor is Chromium 152, with WebMCP testing flags on (no-ops where the surface ships natively). A fixed launch viewport applies in both modes, so a window-manager-decided size never hides a responsive UI in one mode and shows it in another.