AI agents

Ask your coding agent to discover, inspect, and install Sona UI components directly in your project.

Sona UI is designed for source-owned installation. Your agent can use the registry to bring the component into your codebase, then adapt it to your existing tokens and layout.

How the pieces fit

Layer	What it does
`Registry`	Delivers source files, dependencies, and foundations through the Sona namespace.
`Agent catalog`	Helps an agent select a component by intent, capability, accessibility, and motion.
`Sona UI skill`	Teaches the agent how to inspect, install, compose, and validate components.
`MCP`	Gives supported clients natural-language access to the shadcn registry.

The registry namespace is:

text

@sona-ui

Recommended path

Connect your agent.
Install the Sona UI skill.
Ask the agent to find a component by the interaction you need.
Review its detail resource before installation.
Install it through the registry and validate the consumer project.

Example requests

text

Find an accessible tab component for switching between related settings. Do not install anything yet.

text

Inspect @sona-ui/animated-dialog, explain its accessibility and motion behavior, then install it without changing the existing page layout.

text

Find a decorative animated background for a hero section. Check contrast, WebGL support, and reduced motion before recommending an item.

Direct resources

The official shadcn MCP server is the supported MCP path. Sona UI does not require a custom MCP server for registry discovery or installation.

Connect your agent

Configure the Sona UI registry in the project where your agent will work. Then connect the official shadcn MCP server for natural-language discovery and installation.

Add this entry to the components configuration file:

text

components.json

json

components.json

{
"registries": {
  "@sona-ui": {
    "url": "https://sona-ui.vercel.app/r/{name}.json"
  }
}
}

MCP configuration

toml

~/.codex/config.toml

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

Verify the connection

Ask your agent:

text

List the components available from the Sona UI registry and identify the best option for switching between related settings. Do not install anything yet.

The agent should identify this component:

text

fluid-tabs

Explain why it fits and link to its documentation or registry item.

Troubleshooting

If the registry is not found, check that the components configuration contains the Sona namespace and the item URL placeholder shown below. If MCP is not connected, check the client configuration, restart the client, and verify that the official shadcn MCP server appears as connected.

text

{name}

When installation fails, classify the boundary first:

Consumer configuration: aliases, CSS entry point, framework version, or permissions.
Registry payload: missing file, dependency, target, or foundation.
Deployment: a public registry or documentation URL is unreachable.

If the skill is not detected, confirm it was installed to the directory expected by the client, then restart or reload the client. For local registry testing, use:

text

REGISTRY_BASE_URL