# MCP and CLI

Search Siteplane UI components, retrieve complete examples, and install source with shadcn.

## Configure the registry

Complete [Installation](/docs/installation/) for your framework. Merge the Siteplane UI namespace into the target application’s `components.json`:

```json title="components.json"
{
  "registries": {
    "@siteplane": "https://ui.siteplane.io/registry/{name}.json"
  }
}
```

The [registry catalog](/registry/registry.json) includes public components, support dependencies, component examples and application examples. Each item lists its dependencies, and component and example items link their Markdown documentation in `docs`.

With a Siteplane UI Pro license, also add the protected `@siteplane-pro` registry and your license key, as [Installation](/docs/installation/#siteplane-ui-pro) shows. The same commands and tools then search, view and install patterns and their examples, such as `@siteplane-pro/metric-card`.

## Use the CLI

Run commands from the application directory. These examples use pnpm; use `npx shadcn@4.18.0` with npm.

```bash
pnpm dlx shadcn@4.18.0 info --json
pnpm dlx shadcn@4.18.0 search @siteplane -q "button" --json
pnpm dlx shadcn@4.18.0 search @siteplane --type block --json
pnpm dlx shadcn@4.18.0 view @siteplane/button @siteplane/button-demo
pnpm dlx shadcn@4.18.0 add @siteplane/button
```

Search returns names and descriptions; `--type block` lists the application examples. `view` retrieves full source. Read the item’s `docs` URL for the API and composition rules. Siteplane UI documentation is served here; `shadcn docs` searches shadcn’s own documentation and does not resolve Siteplane UI APIs.

## Connect an MCP client

Use the [shadcn MCP server](https://ui.shadcn.com/docs/mcp). It reads the registry configuration from the application working directory. There is no separate Siteplane UI MCP service or API key.

For clients using JSON MCP configuration, add this server to the client’s documented configuration file:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@4.18.0", "mcp"]
    }
  }
}
```

Claude Code uses `.mcp.json`; Cursor uses `.cursor/mcp.json`. VS Code uses `.vscode/mcp.json` with `servers` in place of `mcpServers`. For Codex, add the following to its `config.toml`:

```toml
[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@4.18.0", "mcp"]
```

Restart or reconnect the client after changing its configuration. Open the target application as the working project so the server can find its `components.json`.

## Retrieve only the needed context

| Task                                 | MCP tool                            |
| ------------------------------------ | ----------------------------------- |
| Confirm the Siteplane UI namespace   | `get_project_registries`            |
| Browse components or examples        | `list_items_in_registries`          |
| Find a component by purpose          | `search_items_in_registries`        |
| Read item summaries and dependencies | `view_items_in_registries`          |
| Retrieve complete example code       | `get_item_examples_from_registries` |
| Get the install command              | `get_add_command_for_items`         |

Pass `registries: ["@siteplane"]` when browsing or searching. For source and install commands, use names such as `@siteplane/button` or `@siteplane/team-settings`. Find the default Button example with `query: "button-demo"`; other examples use names such as `select-controlled-example`.

In shadcn 4.18.0, `view_items_in_registries` returns a summary. For component source, use CLI `view` or fetch the item JSON. For complete example source, use `get_item_examples_from_registries`. Follow the item JSON’s `docs` link for Siteplane UI API documentation.

In shadcn 4.18.0, list/search results can show `Add command: [object Promise]`. Use `get_add_command_for_items` to obtain the command. That tool returns `shadcn@latest`; replace it with the documented `shadcn@4.18.0` before execution, preserving the package runner and item names.

The server also provides `get_audit_checklist`. Installation is performed by the returned CLI command; the MCP server does not itself run `add`.

## Troubleshooting

If no registry is found, check the server’s working directory and `components.json`. If search fails, open the catalog URL above. If an item cannot install, read the CLI error and the item’s dependencies before retrying. For an existing file, inspect the incoming diff before choosing whether to replace local changes.

To test the registry configuration without an agent, run the CLI commands above from the same directory.