What is the AIDesigner MCP server?

The AIDesigner MCP server is an HTTP-based Model Context Protocol server that gives AI coding assistants like Claude Code, Cursor, and Windsurf the ability to generate and refine production-ready UI designs.

How do I install the AIDesigner MCP server?

Run "npx @aidesigner/agent-skills init" in your project directory. This registers the MCP server with your AI coding assistant and installs Claude Code agents and commands.

What MCP tools are available?

The server exposes four tools: generate_design (create new UI designs), refine_design (iterate on existing designs), get_credit_status (check your balance), and whoami (view account info).

Server Documentation

AIDesigner MCP Server

Generate and refine production-ready UI designs from Claude Code, Cursor, Windsurf, or any MCP-compatible client.

Terminal

$npx -y @aidesigner/agent-skills init

Quick Start

Get up and running with AI-generated UI inside your existing repository in three minutes.

Package Manager

Initialize the Server

Run the initialization command at the root of your project.

bash

# Install and configure (project-level)
npx -y @aidesigner/agent-skills init

# Or install globally for all repos
npx -y @aidesigner/agent-skills init --scope user

Connect your AI Assistant

Open your MCP client and connect the server.

Claude Code

Run /mcp and select "aidesigner" to connect.

Cursor / Windsurf

Server config is auto-injected into .cursor/mcp.json.

Generate your first design

Open your assistant and prompt it directly. The assistant will utilize the MCP server.

"Use AIDesigner to generate a pricing page with a prominent enterprise plan."

Installation

The MCP Server can be installed per-project or globally. We recommend project-level setup so team members share consistent UI generation rules.

Project-level setup

Creates a .mcp.json in your project root and installs Claude Code agents and commands in .claude/.

bash

npx -y @aidesigner/agent-skills init

User-level setup

Installs globally at ~/.claude so the MCP server is available in every repo.

bash

npx -y @aidesigner/agent-skills init --scope user

What gets created

bash

# Project-level files created by init
.mcp.json                              # MCP server registration
.claude/agents/aidesigner-frontend.md  # Claude Code subagent
.claude/commands/aidesigner.md         # /aidesigner slash command

MCP server configuration

The .mcp.json file registers the HTTP MCP server:

.mcp.json

{
  "mcpServers": {
    "aidesigner": {
      "type": "http",
      "url": "https://api.aidesigner.ai/api/v1/mcp"
    }
  }
}

Verify setup

Run the doctor command to validate your configuration, MCP connectivity, and authentication:

bash

npx @aidesigner/agent-skills doctor

Authentication

The AIDesigner MCP server requires authentication to access remote rendering engines and check quota.

OAuth is Recommended

For local development, the interactive OAuth flow is preferred as it rotates tokens automatically and keeps secrets out of your environment files.

OAuth Flow

1Run aidesigner init to register the server
2Open your MCP client (Claude Code, Cursor, etc.)
3Connect the aidesigner server — a browser window opens for sign-in
4Tokens are stored and refreshed automatically by your client

API Key Fallback

For CI/CD or non-MCP workflows, set an API key directly:

bash

export AIDESIGNER_API_KEY="your-api-key"
npx @aidesigner/agent-skills generate --prompt "landing page hero"

Environment variables

Name	Type	Description
AIDESIGNER_BASE_URL	string	API base URL. Defaults to https://api.aidesigner.ai
AIDESIGNER_MCP_URL	string	MCP endpoint URL. Defaults to {BASE_URL}/api/v1/mcp
AIDESIGNER_API_KEY	string	API key for non-MCP authentication
AIDESIGNER_MCP_ACCESS_TOKEN	string	Direct MCP access token (advanced, for pre-authenticated flows)

MCP Tools Reference

The server registers the following tools with your AI assistant. The assistant automatically decides when to call them based on your natural language prompts.

generate_design

Core

Generate a new HTML/CSS design from a text prompt. Returns a complete HTML document with inline Tailwind CSS.

Parameters

Name	Type	Description
prompt*	string	Natural language description of the design
repo_context*	object	Compact repo summary (framework, tokens, routes). Auto-generated by the CLI.
viewport	"desktop" \| "mobile"	Target viewport. Defaults to desktop (1440px).
mode	"inspire" \| "clone" \| "enhance"	Reference mode (coming soon). See Design Modes. Requires url when set.
url	string	Reference URL for inspire/clone/enhance modes.

// Example Response
{
  "run_id": "2026-03-29T14-30-45-landing-page",
  "html": "<!DOCTYPE html>...",
  "viewport": "desktop",
  "created_at": "2026-03-29T14:30:45.000Z"
}

refine_design

Core

Iterate on a previous design using natural language feedback. Pass either the previous run ID or raw HTML.

Parameters

Name	Type	Description
run_id_or_html*	string	Previous run ID or raw HTML to refine
feedback*	string	What to change — layout, colors, spacing, content, etc.
repo_context*	object	Compact repo summary
viewport	"desktop" \| "mobile"	Target viewport

get_credit_status

Check your credit balance, usage, and subscription status. No parameters required.

json

{
  "primary_remaining": 42,
  "monthly_usage": 8,
  "subscription_status": "active"
}

whoami

Returns the connected account identity and authorized OAuth scopes. No parameters required.

json

{
  "user_id": "user_abc123",
  "email": "dev@example.com"
}

Design Modes

Coming Soon

Both generate_design and refine_design will support optional reference modes that use an existing URL as context.

Inspire

Uses the URL as visual inspiration for a new design. "Make something like this but for our brand."

Clone

Replicates the visual style and layout of the URL. "Match this competitor's aesthetic."

Enhance

Improves the design at the given URL. "Make our current landing page look more modern."

None (Default)

Pure prompt-driven generation, no reference URL. "Design a dashboard for a SaaS analytics tool."

Note

When mode is set, the url parameter is required.

Artifact Storage

Generated designs are saved locally in the .aidesigner/ directory at your project root. Each design gets its own run directory.

.aidesigner/

runs/

2026-03-29T14-30-45-landing-page/

design.htmlGenerated HTML

repo-context.json

request.json

summary.json

preview.png

adoption.json

latest.json

Tip

Add .aidesigner/* and !.aidesigner/.gitkeep to your .gitignore. The init command does this automatically.

Repo context analysis

The CLI automatically analyzes your project and passes context to the MCP server. This includes detected frameworks (Next.js, React, Vue), styling systems (Tailwind, CSS variables), component libraries (Radix, shadcn/ui), route structure, and CSS tokens. This context helps the server generate designs that fit your existing stack.

Adoption briefs

Run aidesigner adopt --id <run-id> to generate a structured porting guide. It identifies your target framework, suggests route placement, maps CSS tokens, and recommends which components to reuse from your existing codebase.

CLI Reference

The @aidesigner/agent-skills package includes a CLI for managing designs locally. These commands are typically called by your AI coding assistant, but you can also run them manually.

Command	Description
init [--scope user]	Install config files and register MCP server
doctor	Validate setup, MCP connectivity, and authentication
generate --prompt "..."	Generate a new design from a text prompt
refine --id <run-id> --prompt "..."	Refine an existing design with feedback
capture --html-file <path> --prompt "..."	Capture MCP output locally
preview --id <run-id>	Render a PNG preview of a design
adopt --id <run-id>	Generate adoption brief (porting guidance)

Common options

Name	Type	Description
--scope	"project" \| "user"	Install scope. project = .mcp.json, user = ~/.claude
--cwd	string	Working directory (defaults to current)
--out-dir	string	Artifact output directory (defaults to .aidesigner)
--viewport	"desktop" \| "mobile"	Target viewport for generation
--mode	"inspire" \| "clone" \| "enhance"	Reference mode (requires --url)
--url	string	Reference URL for inspire/clone/enhance

Troubleshooting

Common issues encountered when connecting the MCP server.

Quick Start

Initialize the Server

Connect your AI Assistant

Generate your first design

Installation

Project-level setup

User-level setup

What gets created

MCP server configuration

Verify setup

Authentication

OAuth is Recommended

OAuth Flow

API Key Fallback

Environment variables

MCP Tools Reference

generate_design

Parameters

refine_design

Parameters

get_credit_status

whoami

Design Modes

Inspire

Clone

Enhance

None (Default)

Note

Artifact Storage

Tip

Repo context analysis

Adoption briefs

CLI Reference

Common options

Troubleshooting

Start designing from your terminal