MCP Support

Connect the Vayu UI MCP server to your AI coding tools for intelligent component discovery, props lookup, scaffolding, and design token access.

The Vayu UI MCP server exposes 17 tools that let AI assistants understand your component library — search components, get props and variants, scaffold code, access design tokens, and more. It runs via stdio, so it works with any MCP-compatible tool.

Quick Setup

The fastest way is using the CLI. All configurations are written at the project level (workspace root):

# Interactive — prompts which tools to configure
npx vayu-ui-cli@latest install-mcp

# Configure specific tools
npx vayu-ui-cli@latest install-mcp --tool claude
npx vayu-ui-cli@latest install-mcp --tool claude,cursor,opencode

This writes the correct config to each tool's settings file in your project root. Restart your AI tool after running it.

Flag	Description
`--tool`	Comma-separated: `claude`, `cursor`, `opencode`
`--dry-run`	Preview changes without writing
`--force`	Overwrite existing entries

Note: The CLI auto-configures Claude Code, Cursor, and OpenCode. For Codex, Antigravity, and Windsurf, use the manual setup below.

Manual Setup

If you prefer to add the config manually, add the JSON (or TOML) below to the correct file for your tool.

File: .mcp.json (project root)

{
  "mcpServers": {
    "vayu-ui": {
      "command": "npx",
      "args": ["-y", "vayu-ui-mcp"]
    }
  }
}

File: .cursor/mcp.json (project root)

{
  "mcpServers": {
    "vayu-ui": {
      "command": "npx",
      "args": ["-y", "vayu-ui-mcp"]
    }
  }
}

File: opencode.json (project root)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vayu-ui": {
      "type": "local",
      "command": ["npx", "-y", "vayu-ui-mcp"]
    }
  }
}

OpenCode uses mcp (not mcpServers) as the top-level key, requires "type": "local", and expects command as an array with arguments merged in.

File: .codex/config.toml (project root)

[mcp_servers.vayu-ui]
command = "npx"
args = ["-y", "vayu-ui-mcp"]

Codex project-level config requires the project to be marked as trusted. If you encounter issues, you can also add the server globally via codex mcp add vayu-ui -- npx -y vayu-ui-mcp.

File: .antigravity/mcp_config.json (project root)

{
  "mcpServers": {
    "vayu-ui": {
      "command": "npx",
      "args": ["-y", "vayu-ui-mcp"]
    }
  }
}

Alternatively, you can install via the MCP Store UI inside Antigravity: open the Agent Panel → More Options (⋯) → MCP Servers → search for custom config.

File: ~/.codeium/windsurf/mcp_config.json (global) or via the MCP Marketplace UI

{
  "mcpServers": {
    "vayu-ui": {
      "command": "npx",
      "args": ["-y", "vayu-ui-mcp"]
    }
  }
}

Windsurf also supports one-click install via the Cascade MCP Marketplace. Go to Settings > Cascade > MCP Servers > Open MCP Marketplace to browse and add servers.

If the file already exists, merge the vayu-ui entry into the existing mcpServers, mcp, or mcp_servers object — don't overwrite other entries.

Project-Level Setup

All MCP configurations managed by this CLI are project-scoped. This means:

Config files are created in your project root, not your home directory.
The MCP server is only active when the AI tool is working inside this project.
Other projects are unaffected.

If you need the same MCP server in multiple projects, run install-mcp in each project directory.

Available Tools

Once connected, the following 17 tools are available to your AI assistant:

Tool	Description
`list_components`	List all components and hooks with optional filters
`find_component`	Fuzzy search by natural language query
`get_component_summary`	Lightweight identity card (name, category, tags)
`get_component_props`	All props with types, defaults, and descriptions
`get_component_variants`	Available visual variants and sizes
`get_component_states`	Interactive states (loading, disabled, hover, etc.)
`get_component_events`	Event handlers with TypeScript signatures
`get_component_a11y`	ARIA roles, keyboard navigation, focus management
`get_component_dependencies`	NPM deps, registry deps, install command
`get_component_peer_components`	Frequently co-used components
`get_component_composition`	Compound component structure and sub-components
`get_component_example`	Ready-to-paste TSX code examples
`get_component_do_not`	Anti-patterns and common mistakes
`get_hook_details`	Full hook API (signature, params, return values)
`scaffold_component_usage`	Generate working code with imports and state
`get_install_guide`	CLI commands and import paths for installation
`get_design_tokens`	CSS design tokens with Tailwind classes

Usage Guide

Recommended Workflow

Discover — list_components or find_component to find the right component
Learn — get_component_props and get_component_a11y to understand the API
Scaffold — scaffold_component_usage to generate copy-paste ready code
Validate — get_component_do_not to avoid anti-patterns

Example: Finding and Using a Component

{
  "name": "find_component",
  "arguments": { "query": "modal dialog with overlay" }
}

{
  "name": "get_component_props",
  "arguments": { "name": "Modal" }
}

{
  "name": "scaffold_component_usage",
  "arguments": { "name": "Modal", "withState": true }
}

{
  "name": "get_component_do_not",
  "arguments": { "name": "Modal", "category": "a11y" }
}

Common Tool Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Component/hook name (case-insensitive)
`slug`	string	No	CLI slug identifier
`variant`	string	No	Example variant key
`category`	enum	No	Filter: `inputs`, `overlay`, `state`, etc.
`type`	enum	No	Filter: `component` or `hook`
`withState`	boolean	No	Wrap scaffold in `useState`

Design Tokens via MCP

Use get_design_tokens to access the full design system:

{
  "name": "get_design_tokens",
  "arguments": { "name": "Button" }
}

Token Categories

Category	What's Included
Colors	Semantic tokens: `brand`, `surface`, `elevated`, `success`, `warning`, `destructive`, `info`, `muted` (each with content variant)
Radius	`rounded-control`, `rounded-surface`, `rounded-overlay`
Shadows	`shadow-control`, `shadow-surface`, `shadow-elevated`
Structural	`border`, `field`, `focus` tokens

Pass overridableOnly: true to get only tokens that are safe to override without breaking component behavior.

Component Categories

Category	Description	Examples
`inputs`	Form controls and data entry	Button, TextInput, Checkbox, Select
`feedback`	Status and feedback	Alert, Spinner, Toast
`overlay`	Modal and overlay UI	Modal, Tooltip, Popover
`layout`	Structural components	Card, Container, Grid
`data-display`	Content presentation	Avatar, Badge, Separator
`navigation`	Navigation components	Navbar, Sidebar, Tabs
`animation`	Animated components	AnimatedContainer, FadeIn
`state`	State management hooks	useLocalStorage, useDebounce
`sensor`	Browser sensor hooks	useMediaQuery, useResizeObserver
`dom`	DOM interaction hooks	useClickOutside, useFocusTrap

Best Practices

Use find_component before assuming — the AI should search for the right component rather than guessing
Check anti-patterns — always run get_component_do_not before generating code
Include accessibility — reference get_component_a11y for ARIA and keyboard requirements
Use the scaffold tool — scaffold_component_usage generates complete code with imports and state
Cache component lists — call list_components once per session, not per request

MCP Support

On this page