AI & MCP

Which one? Local (npx @youj/cli mcp) knows your project (package manager, install route) and your Youj version: use it with Claude Code and Cursor. Hosted is for zero-install; it can't see your project and answers from the latest release.

Connect your AI coding tool to the Youj MCP server, a Model Context Protocol server, to search components, read props and accessibility notes, find icon morphs, check theme contrast and get installation guidance. It's hosted at https://mcp.youj.dev: one line connects it, with nothing to install and no key. The same server is on npm as @youj/mcp, to run on your own machine (see Run it yourself).

The first half of this page is the overview: connecting, what the server can do and how to ask it. The second half is the reference: running it yourself, and every tool, resource and prompt.

#Connect

Point your client at https://mcp.youj.dev. It speaks Streamable HTTP, needs no account or key, is read-only and keeps no session. It answers from the index of the latest Youj release.

#Claude Code, Codex and Gemini CLI

Each has a command that adds the server for every project. Pick yours:

Or put it in the tool's config file. Codex reads ~/.codex/config.toml (or .codex/config.toml in a project), which is TOML:

[mcp_servers.youj]
url = "https://mcp.youj.dev"

Gemini CLI reads ~/.gemini/settings.json (or .gemini/settings.json in a project), where a Streamable HTTP server is httpUrl:

{
  "mcpServers": {
    "youj": { "httpUrl": "https://mcp.youj.dev" }
  }
}

#Cursor

In .cursor/mcp.json (this project) or ~/.cursor/mcp.json (every project):

{
  "mcpServers": {
    "youj": { "url": "https://mcp.youj.dev" }
  }
}

#VS Code

In .vscode/mcp.json:

{
  "servers": {
    "youj": { "type": "http", "url": "https://mcp.youj.dev" }
  }
}

#Windsurf

In ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "youj": { "serverUrl": "https://mcp.youj.dev" }
  }
}

#Zed

In ~/.config/zed/settings.json (every project) or .zed/settings.json (this one):

{
  "context_servers": {
    "youj": { "url": "https://mcp.youj.dev" }
  }
}

#JetBrains AI Assistant

In Settings → Tools → AI Assistant → Model Context Protocol (MCP), choose Add and paste:

{
  "mcpServers": {
    "youj": { "url": "https://mcp.youj.dev" }
  }
}

#Claude.ai and Claude Desktop

In Settings → Connectors, choose Add custom connector, name it Youj and enter https://mcp.youj.dev as its URL. It's then available in every chat, from the tools menu.

#Other clients

Any client that takes a remote server's URL connects the same way: the URL is https://mcp.youj.dev, the transport Streamable HTTP. Opening the URL in a browser shows a short note on how to connect. A client that only runs local servers can run it yourself.

Restart the editor, or reload its MCP servers, after changing its config.

#What it can do

The project tools are read-only and keep reads inside cwd, including symlink targets. Hoisted packages outside it are not inspected; declared ranges are labeled separately from installed versions. Registry configuration takes precedence when both routes are present. Package commands omit dependencies already declared or installed; blocks still need their source copied with get_block.

It also serves every docs page as a resource (youj://docs/<slug>), and two prompts: build-screen and brand-theme.

#Ask it like this

Build a settings page with Youj: profile, notifications and billing tabs.
Make the mute button morph between speaker and muted.
Theme the app for our brand color, #ff5a1f.
Which Youj piece should animate new rows into this table?

Morphing icons are where it earns its keep. Asked for "play → pause", it finds that PlayIcon is choreographed for exactly that pair and hands back the accessible button:

import { PlayIcon, useIconState } from '@youj/icons'

const play = useIconState({ labels: ['Play', 'Pause'] })

<button {...play.buttonProps}>
  <PlayIcon {...play.iconProps} />
</button>

#Docs for any model

Every page is also plain Markdown, for tools without MCP:

• /llms.txt: an index of the docs and blocks, in the llms.txt format.
• /llms-small.txt: every component's import, one-line description and main props.
• /llms-full.txt: every docs page in one file.
• Any page's URL plus .md, such as /docs/components/button.md: that page, with its examples, props and motion tokens as text.

#Run it yourself

The hosted server can't see your project. Run the server on your machine when you want your tool to inspect the app you're working in, or to work offline:

• Your project. Only the local server has get_project_info, and its get_add_command writes the command for your package manager and install route (the hosted one shows npm and says to use your own).
• Your version. The local server answers from an index bundled with the package, so it describes exactly the Youj version it ships with. Pin it to your app's version and the answers match what you have installed.
• Offline. Once it's installed, it needs no network.

The quickest way is the CLI, run in your app:

It asks which editor, writes that editor's config file and pins the server to the Youj version your app has installed. --client picks the editor without asking, and --print prints the config instead of writing it. The CLI reference lists every option.

To add it by hand, put this in your editor's config:

{
  "mcpServers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

{
  "servers": {
    "youj": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

[mcp_servers.youj]
command = "npx"
args = ["-y", "@youj/mcp@latest"]

{
  "mcpServers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

{
  "context_servers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "youj": {
      "command": "npx",
      "args": ["-y", "@youj/mcp@latest"]
    }
  }
}

The snippets use @latest. To match an app on a fixed version, pin the server to it, as the CLI does: @youj/mcp@<version>.

To run the server directly over stdio, for another MCP client or to inspect it:

npx -y @youj/mcp

It needs Node.js 22 or later. When the app in the server's working folder has a different Youj version from the server, the server says so in its instructions and names the matching server to run.

#Tools

Every tool is read-only: none of them writes files or installs anything. They return Markdown sized for a model's context. A name the index doesn't know comes back as an error.

#Find

search: searches by meaning across components, blocks, icons, illustration scenes, loaders (npx @youj/cli add loader-<id>), hooks and docs, and gives each result the tool to call next and the exact way in: the package import, or npx @youj/cli add for what's copied in.

get_component: everything needed to use one component, motion piece, illustration scene (illustration-coffee) or the illustration kit: what it's for and what to use instead, install, usage, props, motion tokens, reduced motion and accessibility.

list_components: every component (UI, core, motion, sound) by docs category, with its package, stability and a one-line summary. Optional kind (ui, core, motion or sound) and category (such as "forms").

list_loaders: every loading animation by category, with its id, component and technique. Optional category. Install one with npx @youj/cli add loader-<id>.

list_miniatures: every miniature (an interactive isometric object) by category, with its id and component. Optional category.

#Icons

search_icons: Youj icons, brand marks and, optionally, Lucide icons by meaning, with synonyms, typos and prefixes. Returns names, a JSX snippet each and the import line.

get_icon: one icon in detail: its choreography, its states (for a morphing icon), its triggers, the accessible button pattern, props, install and IconSwap partners. For a Lucide icon, how to animate it with YoujIcon.

suggest_icon_morph: the best way to animate between two meanings. Returns the state icon made for the pair when one exists, otherwise an IconSwap between the two best icons with the transition that fits, plus the accessible button code.

#Blocks

Blocks are the copy-in levels card, section and screen (an app frame is built in Create). Results name the level.

list_blocks: every block, grouped by domain and tagged with its level, with a one-line summary. Optional group (such as "Auth") lists one group, and level (card, section or screen) lists one level.

get_block: one block: its description, the components it uses, its install command and its files as npx @youj/cli add writes them.

#Illustrations

list_illustrations: the ready-made isometric scenes by category, with their ids and tags. Without category, every category and its scene ids. Read one scene with get_component("illustration-<id>").

get_illustration_guide: how to compose a new scene in the illustration builder's JSON format: the volume and grid, every part type, preset, shade, variant and base, rules that keep a scene readable at small sizes, and worked examples. Takes no input.

draw_illustration: checks a scene in that format. A valid scene comes back as a component for your project's install route, the file to write it to, the install command and a link that opens it in the builder. An invalid scene comes back with every problem and its fix.

#Tokens, themes and motion

get_tokens: a preset's tokens: color (light and dark, with the class to use), type, radius, control size and control heights, motion (durations, easings, springs and staggers), and character (stroke, shadow, title and label voice, icon weight).

create_theme: a theme from a brand color, built with defineTheme over a preset and checked with checkTheme: every text pair at least 4.5:1 and field borders at least 3:1 on every surface, in both modes. A theme that fails WCAG AA is refused unless allowLowContrast is set. Returns the code, how to apply it, the derived colors and any issues.

motion_guidance: names the primitive, preset or token that already does an interaction ("toast enters", "list reorders", "button success", "tabs indicator"), with a snippet, its tokens and its reduced-motion behavior. One input: interaction, in plain words.

#Your project

These tools read the app on disk, so they're on the local server only (the hosted one has get_add_command without the project). Reads stay inside cwd, including symlink targets, so packages hoisted above it aren't inspected. cwd defaults to the server's working folder.

get_project_info: the framework, package manager, install route (the packages or the @youj registry), Youj, React and Tailwind versions, and setup warnings. Installed versions are labeled separately from the ranges in package.json. When an app has both routes, the registry wins. Optional input: cwd.

get_add_command: the exact install command and imports for components, blocks or illustration scenes, for the project's route and package manager, including optional peers and the entry to import from. It leaves out dependencies the app already has. Blocks and scenes get an npx @youj/cli add command, which copies them in. Each name is answered on its own: an unknown one comes back as "Skipped" with suggestions beside the commands for the others (an error only when none is known).

setup: how to add Youj to an app: npx @youj/cli init and the manual steps for the framework and mode, in a component style when given. Paste package.json or the global stylesheet to check versions and stylesheet order, as youj doctor does.

#Resources

#Prompts

#The rules it follows

The server tells your tool to import each thing from the package that owns it, to copy source in only with npx @youj/cli add, to use semantic color classes and Youj sizes rather than raw colors, to take timing from useYouj() or var(--yj-duration-*) rather than hard-coded durations, and to give every animation a reduced-motion equivalent.

#Related