Server Documentation

AIDesigner MCP Server

Generate and refine production-ready UI designs from Claude Code, Codex, Cursor, VS Code / Copilot, or Windsurf.

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
1

Initialize the Server

Run the initialization command at the root of your project.

bash
# Claude Code remains the default
npx -y @aidesigner/agent-skills init

# Configure a project host
npx -y @aidesigner/agent-skills init cursor

# Or configure Codex for just this repo
npx -y @aidesigner/agent-skills init codex --trust-project
2

Connect your AI Assistant

Open your MCP client and connect the server.

Claude Code

Run /mcp and select "aidesigner" to connect.

Codex / Cursor / VS Code / Windsurf

The CLI writes the right host-specific MCP config file and you finish OAuth from that client's MCP panel. In VS Code, use GitHub Copilot in Agent mode.

3

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

Pick the setup guide that matches the MCP client you are actually using. Each client stores config differently and the connection step is slightly different.

Current host support

Claude Code, Codex, Cursor, and VS Code / Copilot support project installs. Windsurf is user-scope only. In VS Code, use GitHub Copilot in Agent mode. In Codex, project-level .codex/ config only loads for trusted repos.
Client

Best if you want the most guided AIDesigner workflow, including Claude-specific agents and the /aidesigner command.

Project setup
bash
npx -y @aidesigner/agent-skills init

Writes: .mcp.json, .claude/agents/aidesigner-frontend.md, .claude/commands/aidesigner.md, and .claude/skills/aidesigner-frontend/SKILL.md

User setup
bash
npx -y @aidesigner/agent-skills init claude --scope user

Writes: ~/.claude/agents/aidesigner-frontend.md, ~/.claude/commands/aidesigner.md, and ~/.claude/skills/aidesigner-frontend/SKILL.md

Connect and authenticate

  1. 1Open Claude Code in the repo.
  2. 2Run /mcp.
  3. 3Select aidesigner and finish browser sign-in.
  4. 4Ask Claude to use AIDesigner or run /aidesigner <your prompt>.

What gets created

bash
# Project scope
.mcp.json                              # MCP server registration
.claude/agents/aidesigner-frontend.md  # Claude Code subagent
.claude/commands/aidesigner.md         # /aidesigner slash command
.claude/skills/aidesigner-frontend/SKILL.md
.agents/skills/aidesigner-frontend/SKILL.md

# User scope
~/.claude/agents/aidesigner-frontend.md
~/.claude/commands/aidesigner.md
~/.claude/skills/aidesigner-frontend/SKILL.md

MCP server configuration

The exact filename and format depend on your host, but every supported client stores the same MCP URL. For example, Claude project setup writes .mcp.json with an HTTP server entry:

.mcp.json (Claude project example)
{
  "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 discovery metadata. You can check one host or every supported host:

bash
npx @aidesigner/agent-skills doctor --all

Upgrading from older installs

Existing MCP installs keep working after you upgrade the package. If your host can already connect and authenticate, you do not need to rerun setup immediately.

Rerun init only if you want the new skill markdown written for that host. Then run doctor <host> to confirm the refreshed setup.

bash
npx -y @aidesigner/agent-skills init codex --trust-project

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

  1. 1Run aidesigner init to register the server
  2. 2Open your MCP client (Claude Code, Cursor, etc.)
  3. 3Connect the aidesigner server — a browser window opens for sign-in
  4. 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

NameTypeDescription
AIDESIGNER_BASE_URLstringAPI base URL. Defaults to https://api.aidesigner.ai
AIDESIGNER_MCP_URLstringMCP endpoint URL. Defaults to {BASE_URL}/api/v1/mcp
AIDESIGNER_API_KEYstringAPI key for non-MCP authentication
AIDESIGNER_MCP_ACCESS_TOKENstringDirect 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

NameTypeDescription
prompt*stringNatural language description of the design
repo_context*objectCompact 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.
urlstringReference URL for preview reference modes when supported.
// 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

NameTypeDescription
run_id_or_html*stringPrevious run ID or raw HTML to refine
feedback*stringWhat to change — layout, colors, spacing, content, etc.
repo_context*objectCompact 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.

CommandDescription
init [host] [--scope user] [--all]Install host-specific MCP config and optional Claude extras
doctor [host] [--all]Validate host config, 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

NameTypeDescription
--scope"project" | "user"Install scope. project writes repo-local MCP config, user writes the selected host's user config
--cwdstringWorking directory (defaults to current)
--out-dirstringArtifact output directory (defaults to .aidesigner)
--viewport"desktop" | "mobile"Target viewport for generation
--mode"inspire" | "clone" | "enhance"Reference mode preview (requires --url and may not be available in every MCP client)
--urlstringReference URL for preview reference modes

Troubleshooting

Common issues encountered when connecting the MCP server.

Start designing from your terminal

One command to connect. Zero context switching. Production-ready UI in seconds.

Learn More

Used by developers building with Claude Code, Codex, Cursor, VS Code, and Windsurf

AIDesigner MCP Server Documentation | Setup & API Reference | AI Designer