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, Codex, Cursor, VS Code/Copilot, 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. Claude Code remains the default when you run "init" without a host.

What MCP tools are available?

The server exposes ten tools. Core design: generate_design, refine_design. Account: get_credit_status, whoami. Editor session pairing: create_editor_session (spin up a new project + auto-pair), link_editor_session (pair with an existing project via 6-char code), unlink_editor_session. Canvas inspection: list_canvases, get_canvas, extract_canvas_design (fuzzy lookup by natural-language query).

How do I pair my coding agent with an editor project?

Either ask your agent to create a new project (create_editor_session returns an editor_url you open), or click 'Connect Agent' in the editor header to mint a 6-character pairing code and tell your agent to call link_editor_session with it. Once paired, generate_design and refine_design calls stream directly onto your canvas.

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

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

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.

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

1Open Claude Code in the repo.
2Run /mcp.
3Select aidesigner and finish browser sign-in.
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.

Run upgrade if you want refreshed generated config and skill markdown for that host. Then run doctor <host> to confirm the refreshed setup.

init still works for this, but upgrade is the clearer command when the host is already installed.

bash

npx -y @aidesigner/agent-skills upgrade codex --trust-project

Authentication

The AIDesigner MCP server is designed around OAuth. Your MCP host opens a browser window for sign-in, then stores and refreshes tokens on your behalf.

Use OAuth for MCP, API keys for REST

MCP clients should use the OAuth flow below. If you are integrating AIDesigner from your own backend or service, use the REST API and provision keys from account settings instead. The full REST reference lives at /docs/api.

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

REST API / helper fallback

For CI/CD or non-MCP workflows, use an API key with the helper or call the REST API directly:

bash

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

Want request schemas, response formats, and credit/error semantics? Read the REST API docs.

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)

Editor Sessions

AIDesigner lets you pair a coding agent to a live editor session so that every design the agent generates streams directly onto the user's canvas. You can see designs appear in real time, pick which ones to adopt, and the agent can read back designs the user has already made.

Option 1 — Agent creates the session

The fastest path. The agent creates a fresh project and pairs itself automatically, then hands you a link to watch.

Ask your agent: "Start a new project and design me a SaaS landing page"
Agent calls create_editor_session and shares the returned editor_url.
Open the link. The "Connected to [Agent]" pill appears instantly.
Agent calls generate_design. HTML streams live onto the canvas.

Option 2 — Pair with an existing session

Use when you already have a project open and want to attach the agent to it.

In the editor header, click the Connect Agent pill.
A 6-character pairing code appears. It expires in 10 minutes.
Give the code to your agent: "Using the AIDesigner MCP, connect to this project with code: ABC-123"
Agent calls link_editor_session. The pill flips to green — you're paired.

After pairing

Every generate_design or refine_design call automatically delivers results to the paired canvas — no extra parameters.
The agent can read existing designs with list_canvases, get_canvas, or extract_canvas_design.
Click Disconnect Agent in the editor pill popover to end the session any time.
Only one agent can be paired to a session at a time per OAuth client. Pairing a different session replaces the link.

Rate Limits

MCP rate limits apply to the slow remote design tools, not to basic discovery calls like initialize, tools/list, get_credit_status, or whoami.

Tool class	Default	Scope
`generate_design` and `refine_design` requests	30 / 60s	Per authenticated account
Concurrent remote generations	4 in flight	Per authenticated account

Single-tool HTTP requests return 429 Too Many Requests with Retry-After and X-RateLimit-* headers when the limit is hit. Batched JSON-RPC calls surface the same condition as a per-entry tool error so other batched requests can still complete.

Backoff guidance

If your MCP host retries automatically, respect the Retry-After header before issuing another generate_design or refine_design call.

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"	Optional reference mode. See Design Modes. Requires url when set.
url	string	Reference URL for clone, enhance, or inspire workflows. Website analysis costs 1 credit, the same as web.

// 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
mode	"inspire" \| "clone" \| "enhance"	Optional reference mode. When refining from a previous run ID, the last mode is reused if omitted.
url	string	Reference URL for clone, enhance, or inspire workflows. When refining from a previous run ID, the last URL is reused if omitted.

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"
}

Editor Session & Canvas Tools

These tools let the agent create new projects, pair with existing editor sessions, and read the user's designs so it can reference or extend them. See Editor Sessions for the end-to-end pairing flow.

create_editor_session

Session

Create a brand-new editor project and automatically pair this agent to it — no pairing code required. Share the returned editor_url with the user so they can watch designs stream in live.

Parameters

Name	Type	Description
title	string	Optional project title shown in the dashboard. Defaults to untitled.
platform_mode	"web" \| "app"	"web" (1440×900) or "app" (430×932 mobile canvas). Defaults to web.

// Example Response
{
  "editor_session_id": "8c9a...-e2b1",
  "editor_url": "https://aidesigner.ai/editor/8c9a...-e2b1",
  "session_title": "Landing page draft",
  "platform_mode": "web",
  "linked_at": "2026-04-19T12:00:00Z",
  "replaced_previous_session_id": null
}

link_editor_session

Pair the agent with an editor session using a 6-character code the user mints from the "Connect Agent" button.

json

// Input
{ "code": "ABC-123" }

// Output
{
  "editor_session_id": "8c9a...-e2b1",
  "session_title": "Landing page",
  "linked_at": "2026-04-19T12:00:00Z"
}

unlink_editor_session

Remove the active pairing. Subsequent generations no longer deliver to the editor canvas. No parameters required.

json

{ "unlinked": true }

list_canvases

Canvas

List all canvases in the linked editor session, newest-first. Use to see what designs the user has before referencing them.

Name	Type	Description
limit	number	Maximum canvases to return (default 50, max 200).

get_canvas

Fetch the full HTML plus metadata for a single canvas by id. Use after list_canvases to read the design source.

json

// Input
{ "canvas_id": "8c9a...-e2b1" }

// Output
{
  "canvas": {
    "id": "...",
    "name": "Pricing Page",
    "slug": "pricing",
    "html": "<!DOCTYPE html>..."
  }
}

extract_canvas_design

Resolve a natural-language query ("the pricing page") to the best-matching canvas via fuzzy trigram matching on name, slug, and text content.

json

// Input
{ "query": "the pricing page" }

// Output
{
  "match_confidence": 0.94,
  "canvas": { "id": "...", "html": "..." }
}

Design Modes

Both generate_design and refine_design support optional reference modes that use an existing URL as context. Use them only when the user explicitly asks for a reference-URL workflow.

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. If the user only mentions a URL as background context, keep the call prompt-driven and do not pass either field.

Tip

Reference-mode website analysis costs 1 credit in MCP, the same as the web app. Use clone for near-1:1 recreation, enhance to improve an existing URL while preserving its goals, and inspire for a new design that borrows style from a reference.

Reference-mode examples

Name	Type	Description
clone	Intent	Use when the user explicitly wants a near-1:1 recreation, such as "clone this website 1:1" or "match this page as closely as possible."
enhance	Intent	Use when the user explicitly wants to improve a specific site, such as "redesign this page" or "make our current landing page feel more modern."
inspire	Intent	Use when the user wants a new design inspired by a specific URL, such as "make something inspired by this site for our brand."
none	Default	Use prompt-only generation when the request is generic or the URL is just background context, such as "design a dashboard for a B2B analytics tool."

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 [host] [--scope user] [--all]	Install host-specific MCP config and optional Claude extras
upgrade [host] [--scope user] [--all]	Refresh generated MCP config and skill files for an existing setup
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

Name	Type	Description
--scope	"project" \| "user"	Install scope. project writes repo-local MCP config, user writes the selected host's user config
--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. clone recreates a URL closely, enhance improves a URL while preserving intent, and inspire uses a URL for stylistic inspiration. Requires --url.
--url	string	Reference URL for clone, enhance, or inspire workflows. Website analysis costs 1 credit, the same as web.

Troubleshooting

Common issues encountered when connecting the MCP server.

Quick Start

Initialize the Server

Connect your AI Assistant

Generate your first design

Installation

Current host support

Connect and authenticate

What gets created

MCP server configuration

Verify setup

Upgrading from older installs

Authentication

Use OAuth for MCP, API keys for REST

OAuth Flow

REST API / helper fallback

Environment variables

Editor Sessions

Option 1 — Agent creates the session

Option 2 — Pair with an existing session

After pairing

Rate Limits

Backoff guidance

MCP Tools Reference

generate_design

Parameters

refine_design

Parameters

get_credit_status

whoami

Editor Session & Canvas Tools

create_editor_session

Parameters

link_editor_session

unlink_editor_session

list_canvases

get_canvas

extract_canvas_design

Design Modes

Inspire

Clone

Enhance

None (Default)

Note

Tip

Reference-mode examples

Artifact Storage

Tip

Repo context analysis

Adoption briefs

CLI Reference

Common options

Troubleshooting

Start designing from your terminal