MCP
Let Claude, Cursor, Codex or Copilot search, read and install Luminix blocks through the shadcn MCP server.
Luminix is a shadcn registry. The shadcn CLI ships an MCP server that reads every
registry listed in your components.json, so your agent can find a block, read
its files and install it without leaving the chat. There is nothing extra to host
or sign up for.
How it fits together
| Layer | What it is | Where it lives |
|---|---|---|
| Agent | Claude Code, Cursor, Codex, VS Code Copilot, OpenCode | Your editor or terminal |
| MCP server | shadcn mcp, started by the agent over stdio | Your machine |
| Registry | registry.json index plus one {name}.json per block | https://ui.luminixstudio.com/r/ |
The agent calls MCP tools. The server turns them into plain HTTP requests against
the registry and returns the JSON. Installing runs the same shadcn add you would
type yourself.
1. Add the registry
Add the @luminix namespace to components.json at the root of your project.
Run npx shadcn@latest init first if the file does not exist yet.
{
"registries": {
"@luminix": "https://ui.luminixstudio.com/r/{name}.json"
}
}2. Connect your agent
mcp init writes the server entry for your client. Restart the client after it
runs.
npx shadcn@latest mcp init --client claudeThis writes .mcp.json:
{
"mcpServers": {
"shadcn": {
"command": "npx",
"args": ["shadcn@latest", "mcp"]
}
}
}Run /mcp in Claude Code to confirm the server is connected.
Any other MCP client works with the same entry: command npx, arguments
shadcn@latest mcp, run from your project root.
3. Ask for blocks
Name the registry in your prompt so the agent searches it:
- “Show me the hero blocks in @luminix.”
- “Find a login page with social sign in from @luminix.”
- “Add hero-1 from @luminix and keep our nav.”
- “Install dashboard-2 and footer-3 from @luminix.”
What the agent can do
| Tool | Use |
|---|---|
get_project_registries | Reads the registries in components.json |
list_items_in_registries | Lists every block, component and theme in @luminix |
search_items_in_registries | Fuzzy search by name or description |
view_items_in_registries | Returns an item's files, dependencies and tokens |
get_item_examples_from_registries | Finds demo usage for an item |
get_add_command_for_items | Returns the shadcn add @luminix/{name} command |
get_audit_checklist | A checklist to verify the install afterwards |
Without MCP
The same registry works from the CLI:
npx shadcn@latest search @luminix -q hero
npx shadcn@latest view @luminix/hero-1
npx shadcn@latest add @luminix/hero-1Troubleshooting
- The agent does not see
@luminix. Make surecomponents.jsonis in the folder the client starts the server from, then restart the client. - Search finds nothing. Check that
/r/registry.jsonloads in your browser. npxcannot be found. GUI clients sometimes start without your shellPATH. Use the absolute path fromwhich npxas the command.