Search visuals

Search the library and jump to any visual preview.

MCP Server

CodedVisuals works with the official shadcn MCP server. Point it at your private registry once, and your AI agent can browse the catalog, search it, and install compositions on its own, without you leaving the editor.

Nothing extra is served on our side. The MCP server reads the same private registry the shadcn CLI uses, so if you already followed the Registry guide, you are most of the way there.

The AI skill is still the recommended path. The MCP server is a good option if you already run it for other registries, or if you prefer keeping everything in one tool.

Skill or MCP server?

Both let an AI agent add compositions for you, from the same registry. They differ in how much the agent knows before it starts:

  • AI skill (recommended). It ships the full catalog, every composition's props and defaults, and the layout patterns for placing them in a section. The agent can pick the right composition for a hero, a bento cell, or a feature block, install it, and wire the props correctly in one pass.
  • shadcn MCP server. Generic registry access: list, search, inspect, and install by name. The agent discovers compositions from their names and descriptions, so it is great for "install the line chart", and less precise for "design this feature section for me".

They are not exclusive. Running both is fine, and a common setup is the skill for picking and placing, the MCP server for everything else you install from shadcn registries.

Before you start

You need an active license, a registry token, and the CodedVisuals registry in your project's components.json. If you have not done that yet, follow Registry first, then come back here.

1. Connect the registry (one time)

In your project's components.json, make sure CodedVisuals is in the registries block, with the header that sends your token:

"registries": {
  "@codedvisuals": {
    "url": "https://codedvisuals.com/r/{name}.json",
    "headers": { "Authorization": "Bearer ${CODEDVISUALS_TOKEN}" }
  }
}

The MCP server reads this file, so the registry has to be configured per project, in the same project you point your editor at.

2. Expose your token

The ${CODEDVISUALS_TOKEN} above is resolved from your environment. Add it to .env.local (or .env) at the root of your project:

CODEDVISUALS_TOKEN=your-token-here

Keep it out of version control, the same way you treat any secret. If it ever leaks, revoke it from Settings, then Registry token and issue a new one.

3. Add the MCP server to your editor

For Claude Code, Cursor, VS Code, and OpenCode, the shadcn CLI writes the config for you. Run the command for your client from your project root:

npx shadcn@latest mcp init --client claude

Swap claude for cursor, vscode, or opencode. Each client keeps the server in its own file, so if you would rather add it by hand, use the snippet for yours below.

Claude Code and Cursor

Claude Code reads .mcp.json, Cursor reads .cursor/mcp.json. Both take the same shape:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

In Claude Code, restart it and run /mcp. You should see the shadcn server listed as connected. In Cursor, enable the shadcn server under Cursor Settings, where it turns green once it is running.

VS Code

VS Code reads .vscode/mcp.json and uses servers instead of mcpServers:

{
  "servers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Then open .vscode/mcp.json and click Start above the shadcn server to run it.

OpenCode

OpenCode reads opencode.json at your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": ["npx", "shadcn@latest", "mcp"],
      "enabled": true
    }
  }
}

Restart OpenCode afterwards.

Codex

Codex is the one client the CLI cannot finish for you: it has no way to write to ~/.codex/config.toml, so add the server there yourself.

[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]

Restart Codex afterwards. That file is global, so the server is then available in every project you open with Codex. The registry itself still comes from each project's components.json.

4. Ask for a visual

Once the server is running, ask for compositions in plain language:

  • "Show me the connections visuals from codedvisuals"
  • "Search codedvisuals for a pricing or comparison visual"
  • "Add the codedvisuals line chart to my features section"
  • "What props does the codedvisuals AI agent flow take?"

The agent resolves the composition from the registry, runs the install for you, and drops the file into components/codedvisuals, exactly as if you had run the add command yourself.

What your agent can do

Through the shadcn MCP server, your agent can:

  • List every composition in your registries, CodedVisuals included.
  • Search them by name and description with fuzzy matching.
  • Inspect a composition, including its source, so it can read the props before using them.
  • Install one or more compositions with the right add command.

Compositions are named {category}-{file}, for example charts-line or sections-timeline, so @codedvisuals/charts-line is what the agent installs.

Troubleshooting

The agent says no registries are configured. The MCP server reads components.json from the project root. Open the project itself in your editor, not a parent folder, and confirm the registries block is there.

The agent cannot see CodedVisuals items. That is almost always the token. Confirm CODEDVISUALS_TOKEN is set in .env.local or .env in the same project, then restart the editor so the server starts with it.

Installs fail with an authorization error. Your token may have been revoked or your license may be inactive. Issue a fresh token from Settings, then Registry token and update your environment.

Nothing happens after setup. Most clients only read their MCP config at startup, so restart yours. Cursor and VS Code also need the server switched on: enable it in Cursor Settings, or click Start in .vscode/mcp.json.

The client reports no tools or prompts. Clear the npx cache with npx clear-npx-cache, then re-enable the server in your client. In Cursor you can read the server logs under View, then Output, choosing MCP: project-* in the dropdown.

Next steps

  • Usage: the props, variations, and snippets for a composition once it is installed.
  • Installation + AI Skills: the recommended AI path, and copy and paste if you prefer it.
  • shadcn MCP docs: the upstream reference for the server itself.