Integrations

MCP — AI integrations

Hook Ajax UI directly into your AI assistant so it always pulls the right component, the right framework, and the right preset.

What is MCP?

The Model Context Protocol is an open standard that lets AI coding assistants — Claude Desktop, Cursor, Windsurf, Zed, and others — talk to external tools over a small JSON-RPC API. We ship two MCP servers:

@ajax-ui/mcp-ui

UI server

The full component registry. Lets the assistant list, search, inspect, and fetch source for any Ajax UI component in any framework.

@ajax-ui/mcp-presets

Presets server

Just themes and design tokens. Use this alone when you only want preset assistance, without the full component catalog mounted.

Setup

Use both servers

The most common setup. The UI server handles “add me a Button”; the Presets server handles “apply my Midnight theme.”

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ajax-ui": {
      "command": "npx",
      "args":    ["-y", "@ajax-ui/mcp-ui"],
      "env":     {
        "AJAX_UI_API_URL": "https://api.ajax-ui.com/v1"
      }
    },
    "ajax-ui-presets": {
      "command": "npx",
      "args":    ["-y", "@ajax-ui/mcp-presets"],
      "env":     {
        "AJAX_UI_API_URL": "https://api.ajax-ui.com/v1",
        "AJAX_UI_API_KEY": "ajx_xxxxxxxx"
      }
    }
  }
}

Cursor

Open Settings → MCP → Edit config and merge in:

{
  "ajax-ui": {
    "command": "npx",
    "args":    ["-y", "@ajax-ui/mcp-ui"]
  },
  "ajax-ui-presets": {
    "command": "npx",
    "args":    ["-y", "@ajax-ui/mcp-presets"],
    "env":     { "AJAX_UI_API_KEY": "ajx_xxxxxxxx" }
  }
}

Windsurf

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

{
  "mcpServers": {
    "ajax-ui": {
      "command": "npx",
      "args":    ["-y", "@ajax-ui/mcp-ui"]
    },
    "ajax-ui-presets": {
      "command": "npx",
      "args":    ["-y", "@ajax-ui/mcp-presets"],
      "env":     { "AJAX_UI_API_KEY": "ajx_xxxxxxxx" }
    }
  }
}

After saving the config

Fully quit and reopen your editor (the MCP servers spawn at startup).
Look for the ajax-ui entry in the MCP/Tools panel — it should show 6 tools available.
First run downloads the package via npx, so give it ~10s on cold start.

Alternative setup

Presets-only setup

Mount just the presets server when you only want the AI to help with theming and design tokens. The full component catalog stays out of context — useful when your assistant has a tool budget.

{
  "mcpServers": {
    "ajax-ui-presets": {
      "command": "npx",
      "args":    ["-y", "@ajax-ui/mcp-presets"],
      "env":     {
        "AJAX_UI_API_KEY": "ajx_xxxxxxxx"
      }
    }
  }
}

Configuration

Both servers read these env vars (pass them in the editor's MCP config):

Variable	Default	Description
AJAX_UI_API_URL	https://api.ajax-ui.com/v1	Registry endpoint. Point at `http://localhost:4000/v1` for local development.
AJAX_UI_API_KEY	—	Required for private preset access and `list_my_presets`. Generate one at Dashboard → API keys.

Tools reference

UI server tools

Tool	Description
list_components	List every component in the registry (optional category filter).
search_components	Fuzzy search components by name.
get_component	Full metadata for one component: description, supported frameworks, tags, version.
get_component_source	Fetch source files for a component in the requested framework. Optionally applies a preset.
list_categories	Distinct categories with component counts.
add_component_command	Returns the CLI command to install components into the user's project.

Presets server tools

Tool	Description
list_public_presets	Browse the public preset gallery (optional framework filter).
list_my_presets	List the authenticated user's presets (public + private). Requires API key.
search_presets	Fuzzy search public presets by name or description.
get_preset	Full preset — tokens, component overrides, metadata.
get_preset_tokens	Just the design tokens, as CSS variables or JSON.
apply_preset_command	Returns the CLI command to apply a preset to the user's project.

Example prompts

Once the servers are mounted, try saying any of these to your assistant:

›Add a date picker and a combobox to my React project.
›Show me every form-control component you can install.
›What's the difference between Modal, Sheet, and Drawer?
›Find a dark, high-contrast preset and apply it to my project.
›Output just the CSS variables from the Midnight preset so I can paste them into globals.css.
›I'm starting a new dashboard — suggest a preset and 6 components to scaffold.

Troubleshooting

The server entry shows red / disconnected in my editor: Quit and relaunch the editor — most clients only read the MCP config at startup. If it still fails, run the binary by hand to see the error: `npx -y @ajax-ui/mcp-ui` (it should print `[ajax-ui-mcp] ready — API: ...` to stderr and then wait for input).
`list_my_presets` says AJAX_UI_API_KEY is required: Add it to the `env` block in your editor's MCP config, then fully restart the editor. The key is loaded once at server boot.
Tools call but the model says the registry is empty: Check `AJAX_UI_API_URL`. If you're running the API locally, it should be `http://localhost:4000/v1`, and the API needs to be running on that port.