# MCP Server

How AI assistants find and install items from your registry.

Source: https://webjs.dev/ui/docs/registry/mcp

Every WebJs app ships a read-only [MCP server](https://webjs.dev/docs/ai-first), reachable as `webjs mcp` or `npx @webjsdev/mcp`. Its `ui` tool lists the WebJs UI components, blocks and charts, and returns one item's helpers, example, install command and files.

The MCP server reads the WebJs UI registry.

The `ui` tool reads the registry that ships inside the installed `@webjsdev/ui` package. An agent reaches your own registry through the CLI, which has a JSON output for exactly this.

## Prerequisites

The CLI reads your registry's index to list it. Make sure `<url>/index.json` is served, as a JSON array of your items. `webjsui build` writes it beside the item files.

For example, if your items are served at `https://acme.com/r/[name].json`, you should have a file at `https://acme.com/r/index.json`. Each entry must conform to the [registry item schema](https://webjs.dev/ui/docs/registry/registry-item-json).

## Configuring an Agent

Tell your registry's consumers to give their agent the registry URL and these commands, for example in their `AGENTS.md`:

```md title="AGENTS.md"
## Acme components

Before writing a component, check the Acme registry:

- List it: npx @webjsdev/ui list --registry https://acme.com/r --json
- Read an item: npx @webjsdev/ui view <name> --registry https://acme.com/r
- Install it: npx @webjsdev/ui add <name> --registry https://acme.com/r
```

`list --json` prints one compact array of `{ name, type, categories, description }`, which an agent can read in one call. `view` prints the item and the source of every file it would write.

```bash
npx @webjsdev/ui list --registry https://acme.com/r --json
```

Then try prompts such as:

- Show me the components in the Acme registry
- Create a landing page using items from the Acme registry

For the WebJs UI registry itself, the agent can use the MCP `ui` tool directly. See the [Skills](https://webjs.dev/ui/docs/skills) page for how agents are told to look for a block before writing a view by hand.

## Best Practices

Here are some best practices for registries agents read:

1. **Clear Descriptions**: Add concise, informative descriptions that help AI assistants understand what a registry item is for and how to use it. `list` prints them.
2. **Proper Dependencies**: List all `dependencies` accurately so `add` can install them.
3. **Registry Dependencies**: Use `registryDependencies` to indicate relationships between items in your registry.
4. **Categories**: Give blocks `categories`, and keep them in the index, so `list --category` can narrow a large registry for an agent. See [Dynamic Search](https://webjs.dev/ui/docs/registry/dynamic-search).
5. **Consistent Naming**: Use kebab-case for item names and maintain consistency across your registry.
