MCP Server

AI Integration

Connect AI assistants to the Airy registry via the Model Context Protocol. Get accurate component lookups, source code, dependency trees, and design guidelines in any MCP-compatible client.

What it does

The Airy MCP server gives AI assistants structured, real-time access to every component, block, hook, guideline, and theme token in the registry. Instead of guessing at APIs and import paths, the AI can look up actual source code, resolve dependency trees, and reference design system rules directly.

Connect

Cursor (one-click)

Install the Airy MCP server into Cursor with one click:

Add to Cursor

Cursor (manual)

Or add to your project's .cursor/mcp.json manually:

{
  "mcpServers": {
    "airy-registry": {
      "url": "https://airy.lev.com/api/mcp"
    }
  }
}

Claude.ai

Go to Settings → Connectors → Add custom connector and paste:

https://airy.lev.com/api/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "airy-registry": {
      "url": "https://airy.lev.com/api/mcp"
    }
  }
}

Local (STDIO)

For faster response times during local development, run the server directly. Build it first:

cd mcp-server && npm install && npm run build

Then point Cursor to the local build:

{
  "mcpServers": {
    "airy-registry": {
      "command": "node",
      "args": ["/path/to/airy/mcp-server/build/index.js"]
    }
  }
}

Tools

The server exposes 12 tools that AI clients can call:

list_components

List all registry items. Filter by type/category and review static discovery fields plus nextActions and inputGuidance.

get_component

Get full details for a component: description, category, dependencies, exports, file paths, and install command.

get_component_source

Get the raw TypeScript/TSX source code of any component in the registry.

search_components

Search by keyword across names, descriptions, categories, and types. Results sorted by relevance.

get_dependency_tree

Recursively resolve all internal (@airy/*) and npm dependencies for a component.

get_guidelines

Get design system guideline docs: code-patterns, visual-design, copy, local-development, or rules.

get_theme_tokens

Get CSS token files: airy (semantic tokens), primitives (base tokens), fonts, or all.

resolve_theme

Resolve an Airy theme to static-ready colors (OKLCH + hex) and font stacks for PDFs, emails, static exports, and sandboxed artifacts.

get_component_static

Get static HTML/CSS snippets by component name (curated or generated) plus resolved theme output.

get_document_template

Get print-friendly static document templates with HTML/CSS and resolved theme output; blocks by default unless required component proofs are supplied.

start_project

Scaffold a new Next.js web app with Airy. Returns step-by-step instructions, starter components, theme config, and AI rules.

get_setup_instructions

Add Airy to an existing project. Returns the components.json registry config, theme install commands, and CSS import setup.

When to use resolve_theme

Use resolve_theme when output cannot resolve CSS custom properties at render time (PDFs, emails, static exports, sandboxed artifacts).

Do not use resolve_theme for normal web app UI with airy.css loaded. In that case, use semantic Tailwind classes and token files from get_theme_tokens.

Static output workflow

For static deliverables (PDFs, one-pagers, sandboxed HTML), start with list_components using type=ui for primitives or type=block for layout scaffolds, then call get_document_template early to retrieve exact required snippet calls before fetching components.

If a category filter is invalid or too narrow, list_components now returns inputGuidance with valid category slugs and starter requests. The same payload includes nextActions tailored to the selected library.

Template responses include componentSnippetsRequired, requiredComponents, and requiredComponentCalls plus explicit required/doNotHandWrite flags so models can fetch required snippets before composing with get_document_template.

get_document_template now blocks by default when required snippet proofs are missing or invalid. Pass componentProofs from prior get_component_static responses (executed exactly from requiredComponentCalls), or explicitly set allowTemplateOnly=true with a valid operator unsafeOverrideKey to override.

Avoid template-only output with hand-written primitive CSS when component snippets are available from get_component_static.

Canonical call sequence: list_components({"type":"ui"}) -> list_components({"type":"block"}) -> get_document_template({"name":"marketing-one-pager","context":"print","theme":"marketing-dark"}) -> get_component_static({...copy requiredComponentCalls[*].arguments exactly}) -> get_document_template({"name":"marketing-one-pager","context":"print","theme":"marketing-dark","componentProofs":[...from get_component_static]}).

Static responses also include staticVersion and limitation notes so generated outputs can be tracked and reviewed when source components evolve.

Resources

3 read-only resources are available for passive context:

Full Registryregistry://all

The complete registry.json with all components, blocks, hooks, and theme files.

Categoriesregistry://categories

All component and block categories with their slugs and descriptions.

Rulesdocs://rules

The AIRY_RULES.md content for AI agent behavior.

Example prompts

Once connected, ask naturally. The AI picks the right tool automatically:

You ask	Tool called
What components does Airy have for forms?	`list_components`
Show me the source code for the sidebar	`get_component_source`
What do I need to install for docs-shell?	`get_dependency_tree`
What are the Airy color tokens?	`get_theme_tokens`
Give me marketing-dark colors and fonts for a PDF export	`resolve_theme`
Give me static HTML and CSS for the card component	`get_component_static`
Generate a marketing one-pager template with print CSS	`get_document_template`
Give me the document-layout template for a printable report	`get_document_template`
How should I compose Airy components?	`get_guidelines`
Find me a chart component	`search_components`
Start a new project called my-dashboard	`start_project`
Add Airy to my existing Next.js app	`get_setup_instructions`