---
title: "MCP server"
description: "Give your editor's agent the registry: what exists, what it looks like, and the command that installs it."
---

`newtui mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
server over the same registry the CLI installs from. With it configured, an
agent stops guessing component names and prop signatures: it lists what exists,
reads the source, and asks for the install command.

The tool names deliberately match shadcn's, so an agent that already knows how
to shop in one registry needs no new vocabulary for this one.

## Quick start [#quick-start]

**Claude Code**

```bash
npx newtui@latest mcp init --client claude
```

Writes `.mcp.json` in the project root. Restart Claude Code and run `/mcp`
to confirm `newtui` is connected.

**Cursor**

```bash
npx newtui@latest mcp init --client cursor
```

Writes `.cursor/mcp.json`. Enable the server in Cursor's MCP settings.

**VS Code**

```bash
npx newtui@latest mcp init --client vscode
```

Writes `.vscode/mcp.json` under the `servers` key, which is where VS Code
looks.

**Codex**

```bash
npx newtui@latest mcp init --client codex
```

Appends an `[mcp_servers.newtui]` block to `~/.codex/config.toml`. Codex
keeps one global config rather than a file per project.

**OpenCode**

```bash
npx newtui@latest mcp init --client opencode
```

Writes `opencode.json` in the project root.

Then ask for something:

- "What newt/ui components are there for showing presence?"
- "Add a chat view with a composer, using newt/ui."
- "Review this diff against the newt/ui checklist."

## What it exposes [#tools]

| Tool                                | What it answers                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| `get_project_registries`            | This project: framework, aliases, Tailwind major, registry, installed components. |
| `list_items_in_registries`          | Every item, with title and description.                                           |
| `search_items_in_registries`        | Items matching a query, so a name is never guessed.                               |
| `view_items_in_registries`          | The full source of an item, without installing it.                                |
| `get_item_examples_from_registries` | A component's demos — the shortest correct usage.                                 |
| `get_add_command_for_items`         | The install command, using the package manager this project already uses.         |
| `get_audit_checklist`               | The rules a newt/ui change is reviewed against.                                   |
| `get_design_tokens`                 | Every `--newt-*` token and its value, dark or light.                              |

Two prompts come with it: `install-component`, which walks the search → view →
install path, and `build-with-newt`, which composes an interface and then checks
itself against the audit checklist.

> **Info**
>
> Every tool is read-only. Installing is `get_add_command_for_items` followed by
> somebody running that command — the write stays out of a tool call nobody
> reviewed.

## Configure it by hand [#manual]

`mcp init` merges into whatever is already in the file. If you would rather
write it yourself:

```json title=".mcp.json"
{
  "mcpServers": {
    "newtui": { "command": "npx", "args": ["newtui@latest", "mcp"] }
  }
}
```

VS Code uses `servers` instead of `mcpServers` and wants `"type": "stdio"`;
OpenCode uses `mcp` with the command as one array; Codex uses TOML:

```toml title="~/.codex/config.toml"
[mcp_servers.newtui]
command = "npx"
args = ["newtui@latest", "mcp"]
```

## Another registry [#registries]

The server answers from the registry the project's
[`components.json`](/docs/components-json) names, so pointing that at
[a registry of your own](/docs/registry) points the agent at it too — the tools
need no separate configuration.

## The docs server [#docs-server]

`newtui mcp` knows the registry; `@newtui/mcp` knows the documentation —
installation per framework, theming, the token reference, the accessibility
notes on every component page. It reads what this site already publishes for
agents (`llms.txt`, `llms-full.txt` and the `.md` twin of every page), so the
answer is the page you are reading, not a recollection of it. Run both.

```json title=".mcp.json"
{
  "mcpServers": {
    "newtui": { "command": "npx", "args": ["newtui@latest", "mcp"] },
    "newtui-docs": { "command": "npx", "args": ["-y", "@newtui/mcp@latest"] }
  }
}
```

| Tool          | What it answers                                                                    |
| ------------- | ---------------------------------------------------------------------------------- |
| `list_docs`   | Every page, with its route, description and section of the sidebar.                |
| `search_docs` | Pages ranked against a few keywords; `content: true` searches page bodies as well. |
| `get_doc`     | One page as Markdown, from a route, a slug such as `button`, or a full URL.        |

Every tool is read-only, and answers are cached in memory for five minutes. The
site defaults to `https://newtui.dev`; `--url` or `NEWTUI_DOCS_URL` points it at
another build — `http://localhost:4321` while you write docs, where full-text
search is not available because the dev server does not serve `llms-full.txt`.

## Troubleshooting [#troubleshooting]

**The server does not appear.** Restart the editor: every client reads its MCP
config at startup. Then run `npx newtui@latest mcp` in a terminal — it should
sit waiting on stdin rather than exiting.

**Tools answer but the project looks empty.** `get_project_registries` needs a
`components.json`. Run `newtui init` first.

**The registry cannot be reached.** The tools fetch over HTTPS at call time. On
a restricted network, set `NEWT_REGISTRY_URL` to a mirror you can reach.