Skip to content
{gui.}

Getting started with AI

GolemUI shipped after the training cutoff of every current model — so your AI assistant has never seen it. On its own, it will guess at the API, and guesses break the runtime. The GolemUI MCP fixes that: it grounds the assistant in the real, current GolemUI schemas at build time, so it generates correct forms instead of inventing them. This page takes you from nothing to a form your AI built.

Why your AI needs the MCP

Section titled “Why your AI needs the MCP”

Without grounding, an assistant has no reliable knowledge of GolemUI: it will reach for widget kinds and prop names that look plausible but don’t exist, and one wrong property breaks the form. The MCP is the grounding layer that closes the gap.

It is deterministic — no LLM calls happen inside it. It ships a frozen snapshot of the real GolemUI API, version-locked to a GolemUI release, and exposes tools your assistant calls to look up that API and check its own work. Because we’re asking for the typed {gui.} builder, the two that matter most here are:

  • dx_list_factories — the complete gui.* builder reference in one call: every factory with a compile-verified example and its gotchas, plus imports tailored to your framework. The assistant calls this first, then writes the form from it.
  • dx_check_code — type-checks the generated gui.* code against the real @golemui declarations and returns { ok, diagnostics }; the assistant fixes what it flags and re-checks until it’s clean.

(If you instead start from a JSON Schema or OpenAPI spec, the JSON-surface tools — json_generate_from_schema, json_generate_from_openapi, json_get_widget_spec, get_concept, json_validate_form_definition — handle that path.)

The assistant works in a tight look-up → write → check loop: ground itself, write the form, verify, fix what’s flagged, repeat until clean. See the MCP overview and tools reference for all eight tools.

JSON or {gui.}? Tell the AI which

Section titled “JSON or {gui.}? Tell the AI which”

A GolemUI form can be authored two ways, and the assistant won’t guess — say which you want in your prompt:

  • Writing a normal app? Ask for the typed {gui.} builder. TypeScript, autocompleted, type-checked, smaller, and easy to review — the right default when the form lives in your codebase. It’s what the prompt below uses.
  • Need the form as portable data — stored in a database or CMS, generated at runtime, sent over the wire? Ask for a JSON form definition instead. (Already have a JSON Schema or OpenAPI spec? The MCP maps it straight to a form — see Generating from a schema.)

Same engine, same widgets — only the surface differs, and the MCP grounds and validates both (dx_check_code for {gui.}, json_validate_form_definition for JSON).

Step 1 — Set up the MCP

Section titled “Step 1 — Set up the MCP”

Two ways in, depending on your tool. Either way, the MCP has to be live before you prompt — its tools load when the assistant starts.

The cleanest flow: add the MCP in a fresh folder, then start Claude there — so the tools are loaded from your first message and there’s nothing to restart.

  1. Create an empty folder for the app and open it:

    Terminal window
    mkdir my-form-app && cd my-form-app

  2. Add the GolemUI MCP in that folder:

    Terminal window
    claude mcp add golemui -- npx -y @golemui/gui-mcp

  3. Start Claude Code in the folder — open the desktop app on it, or run claude in the terminal.

  4. (Optional) Confirm it’s connected: claude mcp list shows golemui ✓ Connected.

Step 2 — Describe your form

Section titled “Step 2 — Describe your form”

With the MCP connected, you don’t write GolemUI by hand — you describe the form in plain English and let the assistant build it, grounded by the MCP. Here’s a ready prompt: pick your framework and copy it into your AI.

✦ Prompt 
Build a simple Contact form.

The form has the following fields (use the natural input type for each):
1. Full name — text, required.
2. Email — text, required; must be a valid email address.
3. Subject — a dropdown: Question / Feedback / Bug report, required.
4. Message — a multi-line textarea, required.

Give the form a clear title, validate every field, and keep the submit button disabled until the form is valid.

Build this form with GolemUI (React). Ground yourself in the real GolemUI API through the GolemUI MCP — GolemUI's recommended channel — and write it with GolemUI's typed gui.* TypeScript builder (verified through the MCP), not a raw JSON schema.

Build it into a fully functional, runnable app — scaffold the project, wire it all up, and verify it compiles and runs.

We ran the benchmark with Claude — Opus, Sonnet, and Haiku. AIs aren't deterministic, so the same prompt won't produce identical code twice: your output will vary run to run, and other models may land elsewhere. Grounding through the MCP is what keeps results consistent.

The prompt does two things on purpose: it tells the assistant to ground itself through the MCP, and to author the form with GolemUI’s typed {gui.} builder rather than a raw JSON schema — the builder is smaller, typed, and far easier to review.

Step 3 — What good looks like

Section titled “Step 3 — What good looks like”

You’ll know the MCP did its job when:

  • The assistant called the GolemUI tools — you’ll see dx_list_factories and dx_check_code in its tool log, not silence.
  • The form is authored with the typed {gui.} builder, e.g. one gui.inputs.* call per field, not a hand-written JSON blob.
  • It ran dx_check_code and fixed every type error before finishing.
  • The app compiles, the form renders, and the validation actually works.

Going further

Section titled “Going further”
  • Form Studio — an AI-assisted, low-code form builder. A free open-source community edition runs on Cloudflare Workers with just an Anthropic API key; the hosted Pro edition adds accounts and storage.
  • llms-gui-dx.txt — a self-contained DX reference an AI form builder can read in one pass and write a whole form from, for assistants that can’t use the MCP. It’s the docs-channel fallback; the MCP is the recommended path.
  • Tools reference — every tool’s inputs, outputs, and when to reach for each.

Troubleshooting

Section titled “Troubleshooting”
  • It wrote raw JSON instead of the typed builder. Ask it to use the {gui.} builder. Both validate against the same schemas, but the typed builder is smaller and easier to review — and it’s what you’ll want to maintain.
  • It used a widget or prop that doesn’t exist. The assistant isn’t grounded. Confirm the MCP is connected (claude mcp list, or Verify), then retry — grounded, it validates against the real schemas.
  • It never called the MCP. Make sure the server shows as connected and the tools are visible in the assistant, then restart your IDE. Telling it explicitly to “use the GolemUI MCP” helps.
  • Build errors. Install the framework package (npm i @golemui/gui-react, -vue, -angular, or -lit) and import the styles once: @import '@golemui/gui-components/index.css';.