Skip to content
helix-ui

Claude Code

Claude Code is Anthropic’s CLI agent. helix-ui ships an MCP server it can speak to natively.

One-line setup

From a checkout of helix-ui (or a project with helix-ui installed):

Terminal window
claude mcp add helix-ui node ./node_modules/@helix-ui/mcp/bin/server.mjs

Restart Claude Code and the helix-ui.* tools are available. Ask it something like:

Use helix-ui.search to find the right component for “selectable list of options with chips” — then write the JSX.

Project-level CLAUDE.md

Drop this into your repo root so every Claude Code session in this project starts with the right context:

# CLAUDE.md — conventions for this project


This project uses **helix-ui** as its design system. helix-ui is AI-native;
you should treat it as a first-class source of truth.


## Components & tokens


- Import components from `@helix-ui/core`. Never inline-style what a
  helix-ui component already provides.
- Token names live in `tokens-manifest.json`. If you need a token, use
  the helix-ui MCP server's `helix-ui.search` to find it; do not invent
  values.
- Each component's contract lives next to its source as `spec.md`.


## How to look things up


Before writing UI, use the MCP server:


- `helix-ui.search` — BM25 lookup across every component spec.
- `helix-ui.validate` — confirm a generated JSX snippet is legal.
- `helix-ui.list_presets` — list DNA presets.
- `helix-ui.express_dna` — expand a DNA shorthand into a DESIGN.md.


## What to avoid


- Don't write CSS-in-JS. Use CSS variables.
- Don't pass `style={{ color: '#...' }}`. Use tokens.
- Don't add a new dependency without justification in the PR.


## When unsure


- Read `DESIGN.md` at the repo root.
- Read `/llms-full.txt` for the full system snapshot.

Example prompts that work

These all should succeed on the first try:

Build me a settings page with:
- email notifications toggle
- two-factor auth section with a "Configure" button
- a danger zone with a "Delete account" red button


Use helix-ui components and the helix-ui DNA theme.
Take this DNA shorthand: { basePreset: 'noir', mutations: [{ gene:
'accent', value: 'violet' }] }, expand it via helix-ui.express_dna,
and apply it as DESIGN.md to a new module.
The user just dropped a screenshot at ./logo.png. Use
helix-ui.derive_dna_from_image with adapter:'anthropic' to pick the
closest helix-ui DNA, then preview the result.

Troubleshooting

“Tool helix-ui.search not found.” → Restart Claude Code. The MCP servers list is read at startup.

The server starts but tools are empty. → Run pnpm build:all once. The MCP server reads from apps/site/dist/*.json; without a build the manifest is empty.

The vision adapter throws. → OPENAI_API_KEY / ANTHROPIC_API_KEY must be in the MCP launch env, not your shell env. Add them to the env block in your Claude Code config.

Where the server lives

In a checkout: packages/mcp/bin/server.mjs. After pnpm add @helix-ui/mcp: node_modules/@helix-ui/mcp/bin/server.mjs.

See the package README for the full tool list and protocol details.