# Using Assembli from a coding agent

Assembli exposes the same component library to agents in five ways. Pick whichever your tool supports.

## Set up your agent

Add the MCP server at `https://www.assembli.design/mcp`, then sign in once in the browser when the client asks. There's no API key to copy: the client is issued one through OAuth.

### Claude Code

Add the plugin, then sign in once from `/mcp`.

1. **Add the marketplace.** Run this inside Claude Code.

```bash
/plugin marketplace add assembli-ui/claude-plugin
```

2. **Install the plugin.** Then this, on its own. The plugin adds the MCP server and a skill that tells Claude when to reach for the library.

```bash
/plugin install assembli@assembli
```

Or add just the MCP server, from your terminal:

```bash
claude mcp add --transport http assembli https://www.assembli.design/mcp
```

3. **Sign in.** Run `/mcp`, pick assembli and choose Authenticate. Your browser opens: sign in and click Allow. Search works on any account; source needs Pro, and unlocks the moment you subscribe.

### Codex

Two commands in your terminal.

1. **Add the server.** Registers Assembli in `~/.codex/config.toml`.

```bash
codex mcp add assembli --url https://www.assembli.design/mcp
```

2. **Sign in.** Your browser opens: sign in and click Allow. Search works on any account; source needs Pro, and unlocks the moment you subscribe.

```bash
codex mcp login assembli
```


### Cursor

One click to add the server, then sign in from Cursor's MCP settings.

1. **Add the server.** Use the Add to Cursor button, or put this in `.cursor/mcp.json` (one project) or `~/.cursor/mcp.json` (everywhere):

```json
{
  "mcpServers": {
    "assembli": {
      "url": "https://www.assembli.design/mcp"
    }
  }
}
```

2. **Sign in.** Open Cursor Settings → MCP and click the login button next to assembli. Your browser opens: sign in and click Allow. Search works on any account; source needs Pro, and unlocks the moment you subscribe.

One-click install: cursor://anysphere.cursor-deeplink/mcp/install?name=assembli&config=eyJ1cmwiOiJodHRwczovL3d3dy5hc3NlbWJsaS5kZXNpZ24vbWNwIn0=

### Other clients

Any client with remote MCP and sign-in support takes the URL on its own.

- **Claude Desktop and claude.ai.** Settings → Connectors → Add custom connector. Paste the URL, then click Connect and sign in.

```bash
https://www.assembli.design/mcp
```

- **Clients that take a URL.** Add it as a Streamable HTTP server. The client asks you to sign in the first time it connects.

```json
{
  "mcpServers": {
    "assembli": {
      "url": "https://www.assembli.design/mcp"
    }
  }
}
```

- **stdio-only clients.** Bridge with mcp-remote, which handles the sign-in for you:

```json
{
  "mcpServers": {
    "assembli": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.assembli.design/mcp"
      ]
    }
  }
}
```


### shadcn CLI

No MCP: install straight into your project from the @assembli registry. The CLI can't sign in, so it uses an API key.

1. **Add the registry to components.json.** Once per project.

```json
{
  "registries": {
    "@assembli": {
      "url": "https://www.assembli.design/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ASSEMBLI_API_KEY}"
      }
    }
  }
}
```

2. **Add an API key to .env.local.** Create one on your account page (needs Pro) and paste it in: (https://www.assembli.design/account)

```bash
ASSEMBLI_API_KEY=asm_…
```

3. **Install.** Search is free; installing reads the key from `.env.local`.

```bash
npx shadcn@latest search @assembli -q "pricing"
npx shadcn@latest add @assembli/pricing-cards
```


## Skill

The Claude Code plugin includes the Assembli skill. To install only the skill:

```bash
mkdir -p ~/.claude/skills/assembli && curl -fsSL https://www.assembli.design/skill.md -o ~/.claude/skills/assembli/SKILL.md
```

## Prompts for common jobs

### Find and install a component

Describe what you need. The agent searches, checks the preview, installs it with its dependencies and wires it in. (Search free · install with Pro)

```text
Find a component in the Assembli library (https://www.assembli.design) for: <describe what you need and where it goes>.

1. Search with the MCP tool `search_components`, or `GET https://www.assembli.design/api/components?q=<query>&limit=10`.
2. Pick the best two or three matches and show me their preview links before choosing.
3. Install it. With the Assembli MCP server, call `get_component`, write the component file it returns to `components/<slug>/<slug>.tsx` and install its `dependencies` and `registryDependencies`. Without it, run `npx shadcn@latest add @assembli/<slug>` (setup: https://www.assembli.design/agents.md).
4. Use it where I said, keep its props API, and match the copy and colors to this project.
```

### Start from a landing page

Full single-file pages, grouped by industry. Pick one that fits, install it and swap in your own content. (Pro)

```text
Build this project's landing page from an Assembli template (https://www.assembli.design).

1. List the landing-page types with `list_categories` (or `GET https://www.assembli.design/api/categories`) and pick the one closest to this product.
2. Get candidates with `search_components` filtered to `category: "landing-pages"` and that `subcategory`, and show me their previews.
3. Install it. With the Assembli MCP server, call `get_component`, write the component file it returns to `components/<slug>/<slug>.tsx` and install its `dependencies` and `registryDependencies`. Without it, run `npx shadcn@latest add @assembli/<slug>` (setup: https://www.assembli.design/agents.md). Render it on the home route.
4. Replace the fictional brand, copy and images with this product's, using its README and existing pages as the source of truth.
```

### Load the catalog into context

Give an agent the whole index in one fetch, so it can suggest components while it builds. (Free)

```text
Read https://www.assembli.design/llms.txt so you know what's in the Assembli component library.

While you build UI in this project, check it before writing a component from scratch. When something fits, tell me the slug and preview link, then: Install it. With the Assembli MCP server, call `get_component`, write the component file it returns to `components/<slug>/<slug>.tsx` and install its `dependencies` and `registryDependencies`. Without it, run `npx shadcn@latest add @assembli/<slug>` (setup: https://www.assembli.design/agents.md).
```

## Access

Searching, browsing, metadata and live previews are free. Component **source** (registry items, `get_component`, the source sections of the Markdown pages, `/api/components/<slug>` files) needs an Assembli subscription ($12/month), one component at a time: an account can read the source of up to 60 different components per day, which is plenty for building, and re-reading one is free.

### Sign in over MCP (recommended)

`https://www.assembli.design/mcp` uses OAuth 2.1 with dynamic client registration and PKCE. MCP clients that support sign-in (Claude Code, Cursor, Codex, claude.ai) handle it themselves: in Claude Code the user runs `/mcp`, picks assembli and chooses Authenticate. If `get_component` reports the source as locked, the account needs a subscription (https://www.assembli.design/?pricing=open); the connection keeps working once they subscribe.

### Connect with device login (agents without sign-in)

You can start this yourself. The user only has to click a link, sign in, approve and subscribe if they haven't yet. You never handle their login or payment.

```bash
curl -X POST https://www.assembli.design/api/agent/login -H "content-type: application/json" -d '{"client_name":"Claude Code"}'
```

1. Show the user `verification_uri_complete` and the `user_code`, and ask them to approve.
2. Every `interval` seconds (5), poll until the response has `api_key`. While waiting it returns `{"error":"authorization_pending"}`; `slow_down` means poll less often, and `access_denied` or `expired_token` mean stop.

```bash
curl -X POST https://www.assembli.design/api/agent/token -H "content-type: application/json" -d '{"device_code":"asmd_…"}'
```

3. Save the key right away (it is shown once), e.g. `ASSEMBLI_API_KEY=asm_…` in `.env.local`, and send it as `Authorization: Bearer asm_…` with every request. If `subscribed` is false, ask the user to subscribe at https://www.assembli.design/?pricing=open; the same key then works.

On the open MCP endpoint (`https://www.assembli.design/api/mcp`), the `connect_account` and `finish_connect` tools do the same thing.

### Or create a key by hand

Subscribe at https://www.assembli.design/pricing, create a key at https://www.assembli.design/account (it starts with `asm_`) and send it as `Authorization: Bearer asm_…`.

## 1. MCP server

Streamable HTTP endpoint: `https://www.assembli.design/mcp` (OAuth sign-in; API keys work too)

Tools: `search_components`, `list_categories`, `get_component` (source with a subscription).

```bash
claude mcp add --transport http assembli https://www.assembli.design/mcp
```

Without sign-in: `https://www.assembli.design/api/mcp`. Search is open, `get_component` returns source for an API key, and `connect_account` / `finish_connect` run device login for a key.

```bash
claude mcp add --transport http assembli https://www.assembli.design/api/mcp --header "Authorization: Bearer $ASSEMBLI_API_KEY"
```

## 2. shadcn registry

Registry items live at `https://www.assembli.design/r/<slug>.json` (index: `https://www.assembli.design/r/registry.json`). Set the registry up once:

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

```bash
npx shadcn@latest add @assembli/<slug>
```

## 3. Markdown

Append `.md` to any page URL, or send `Accept: text/markdown`, to get a Markdown version. Component pages include full source when the request carries an API key.

```bash
curl -H "Authorization: Bearer $ASSEMBLI_API_KEY" https://www.assembli.design/components/<slug>.md
```

## 4. JSON API

- `GET https://www.assembli.design/api/components?q=&category=&subcategory=&tag=&limit=`: search and filter (`subcategory` is a type within a category, e.g. `saas` landing pages)
- `GET https://www.assembli.design/api/components/<slug>`: metadata and install commands; with an API key, also source files and a ready-made agent prompt
- `GET https://www.assembli.design/api/components/<slug>?format=package`: a single JSON document you can pass to `pnpm registry:import` (API key)
- `GET https://www.assembli.design/api/categories`: categories with counts, and their types where they have them

## 5. llms.txt

- `https://www.assembli.design/llms.txt`: index of every component with links to its Markdown