RetroDeckRETRODECK

How to Connect Meta's Astryx Design System to Claude Code With MCP

To connect Astryx to Claude Code, install @astryxdesign/cli and run claude mcp add astryx -- npx @astryxdesign/cli mcp, or use the hosted docs server at https://astryx.atmeta.com/mcp. Astryx's own docs prefer the CLI for agents that run commands: npx @astryxdesign/cli init writes the rules into CLAUDE.md.

What Astryx is, and what the video shows

Astryx is a React design system that Meta published as open source under the MIT license, in public beta, in mid-2026. The repository lives at github.com/meta/astryx and the docs at astryx.atmeta.com. It is built on React 19 and StyleX, Meta's compile-time CSS engine, but consumers import prebuilt CSS and typed components, so no build plugin is required. Meta's README says the system grew internally over eight years and powers more than 13,000 apps; that is Meta's own figure.

The package set is small: @astryxdesign/core for components, @astryxdesign/cli for tooling, and seven theme packages (neutral, butter, chocolate, matcha, stone, gothic and y2k). The README claims 150+ accessible components. The repository passed 31,000 GitHub stars by 20 November 2026.

The Korean video behind this page, from the Builder Josh channel (15 November 2026), walks through installing Astryx, connecting its MCP server to Claude Code, and asking the agent to list real components such as Button, TextInput and Table instead of inventing its own. That is the whole point of the integration: the agent looks up the actual component and its props rather than guessing.

Two ways to connect Astryx to Claude Code over MCP

Astryx serves MCP in two forms, and they answer different questions. Pick based on whether Astryx is already installed in the project.

The local server, inside a project

Install the packages first: npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex, then npm install -D @astryxdesign/cli. Then register the CLI as a stdio server:

claude mcp add astryx -- npx @astryxdesign/cli mcp

The same entry can go in the project's .mcp.json with command npx and args ["@astryxdesign/cli", "mcp"]. Every CLI command that supports --json becomes one tool, named by its words (theme build becomes theme_build), and each call runs against the Astryx version, theme and integrations your project actually has. If the project has no agent docs yet, the server hands the agent the guidance text that init would have written.

The hosted server, with nothing installed

For browsing before you commit, point Claude Code at the docs site:

claude mcp add --transport http astryx https://astryx.atmeta.com/mcp

This is the same server run with --docs-only. Its tools are read-only: search, build, component, hook, docs, template, discover, theme list and theme targets. It answers for the latest published release, not for your project, takes one JSON-RPC message per request, and refuses any input that names a folder or a file to write. The endpoint answered a tools/list request when this page was written.

Why Astryx's own docs say start with the CLI

The Astryx documentation is direct about this: an agent that can run commands should run the astryx CLI itself, and MCP is for tools that cannot run commands or reach tools only through MCP. Claude Code can run commands, so the recommended path there is:

npx @astryxdesign/cli init

Init asks no questions. It writes an Astryx block into AGENTS.md, and because Claude Code skips AGENTS.md when a CLAUDE.md exists, it writes the same block into CLAUDE.md too. That block carries the component index, the behavioural rules and a CLI reference. The repository also ships a Claude Code plugin that tells the agent Astryx is available and when to reach for it.

The practical reason to prefer the CLI is context cost and freshness. MCP tool definitions can occupy the context window on every turn unless the client defers them, while a CLI call costs tokens only when the agent uses it. The CLI also always answers for the installed version. Use the hosted MCP server for exploration, the CLI or the local server for real work.

A working session: build, template, component

The guidance init writes teaches a three-step loop before any UI code. First, build with a plain description of the page returns the closest page template, two alternatives, and the components for the parts the template lacks. Second, template with a name and a path scaffolds that template into the project, and the agent keeps its frame and spacing while replacing the content. Third, component with one or more names prints the import, usage and props for every component used.

The rules that come with it are what stop drift: start every page from a template, no raw divs, no inline style objects, and design tokens instead of magic values. Theming is a set of CSS custom property overrides, so switching from neutral to matcha does not touch component code.

To check the setup, the docs suggest asking the agent three questions before it writes anything: the import path for Button, how to make a Dialog non-dismissible, and which prop Selector uses for its items. If it cannot answer all three, it has not read the agent docs, and it should run init and read the generated file.

What to weigh before adopting it

Astryx is in beta, with the CLI at version 0.7.x on npm in November 2026, so package names, commands and flags can still change. Pin versions and rerun upgrade after a bump, since it refreshes the agent docs block.

Version skew is the subtle trap with the hosted server. It documents the latest release, so an agent connected only to it can suggest props your installed version does not have. In a project, the local server or the CLI avoids that.

Coverage reporting such as InfoQ's has noted developer concerns about long-term maintenance and governance of a Meta-sponsored system. The swizzle command, which copies a component's full source into your repo, gives you an exit, but anything you eject becomes yours to maintain.

The part a design system's MCP does not cover

Astryx's server knows Astryx. It does not know which of its 150 components your team standardised on, the product rules your designers wrote down, or why a page looks the way it does. That knowledge usually lives in notes and old pull requests, and agents rediscover it at full token cost every session.

RDK indexes those files as encrypted private chunks, so an agent queries your conventions through MCP or the CLI and gets a few hundred tokens of context instead of whole documents. On repeated, reference-heavy work like this, retrieval cuts token spend by 80 to 90 percent because the answer is looked up rather than regenerated. Pair the library's server with your own.

Frequently asked questions

Is Astryx really from Meta?
Yes. The repository is github.com/meta/astryx, published by Meta under the MIT license, with docs at astryx.atmeta.com. Meta describes it as a design system that grew internally over eight years and powers more than 13,000 apps. It is in public beta, so treat the API as subject to change and pin your versions.
What is the command to add Astryx to Claude Code?
Inside a project with Astryx installed, run claude mcp add astryx -- npx @astryxdesign/cli mcp to serve every CLI command as a tool. With nothing installed, run claude mcp add --transport http astryx https://astryx.atmeta.com/mcp to use the hosted, read-only docs server for the latest release.
Is MCP required to use Astryx with Claude Code?
Usually not. Astryx's docs recommend that agents able to run commands, which includes Claude Code, use the CLI directly. Running npx @astryxdesign/cli init writes the agent guidance into CLAUDE.md and AGENTS.md. MCP is intended for tools that cannot run commands or only reach tools through MCP.
Which themes does Astryx include?
Seven: neutral, butter, chocolate, matcha, stone, gothic and y2k, each published as an @astryxdesign/theme package. A theme is a set of CSS custom property overrides, so a designer can restyle the system or author a new theme without forking or wrapping component source. Dark mode is supported across the system.