MCP Support

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 SetupCopy Anchor Link

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.

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

Manual SetupCopy Anchor Link

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

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

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 SetupCopy Anchor Link

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 ToolsCopy Anchor Link

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

Usage GuideCopy Anchor Link

Recommended WorkflowCopy Anchor Link

1. Discover — find_component (or list_components for broad browsing), then get_component_summary
2. Inspect — get_component_props, get_component_variants, get_component_states, and get_component_events
3. A11y + composition — get_component_composition and get_component_a11y for overlays/forms/keyboard paths
4. Scaffold + validate — scaffold_component_usage, then get_component_do_not
5. Install/import verification — get_install_guide before sharing commands/import paths

Example: Finding and Using a ComponentCopy Anchor Link

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

Common Tool ParametersCopy Anchor Link

Design Tokens via MCPCopy Anchor Link

Use get_design_tokens to access the full design system:

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

Token CategoriesCopy Anchor Link

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

Component CategoriesCopy Anchor Link

Best PracticesCopy Anchor Link

• 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

Project setup and import accuracyCopy Anchor Link

npx vayu-ui-cli@latest install-mcp --tool claude,cursor,opencode,vscode,codex --force

Setup merges the Vayu entry with existing server settings. It supports JSON comments for VS Code and TOML for Codex. --dry-run previews changes; malformed configuration stops setup before any selected file is modified.

Restart or reload your client after setup. Codex loads project MCP configuration in trusted projects; see the official Codex MCP documentation. VS Code uses a servers object with type: "stdio", as described in its MCP documentation.

Before requesting generated usage, read vayu-ui.config.json. Pass its uiPath, paths, and aliases as config, and pass the target source filename as fromFile, to get_install_guide or scaffold_component_usage. Their default is CLI-copied sources. Use mode: "package" only when the application installs the vayu-ui npm package.

Scaffolding uses registry examples with valid compound nesting and returns the slugs used by the snippet. Application headings and paragraphs use Typography. Overlay titles retain Modal.Title / Drawer.Title so their accessible IDs stay connected.