Getting Started with GradientDeck MCP

GradientDeck MCP is a Model Context Protocol server that gives your AI coding agent access to 17,000+ design assets, 13 code generators, a 58-gate anti-AI-slop audit, and a design advisor that recommends, critiques, and explains — all through a single URL. No accounts, no API keys, no database. Read-only and stateless.

What you get (29 tools)

The MCP exposes three layers of tools your agent can call:

Layer 1 — Catalog & code generation (17 tools)

These tools let your agent browse the asset catalog and generate code in CSS, Tailwind, React/TSX, SVG, or JSON:

• list_asset_kinds — see what's available (gradients, patterns, animations, icons, palettes, Tailwind colors, mesh, shadows, glass presets) with counts per kind.
• search_assets — search by free-text query, kind, colors, or tags. Returns concise entries; use get_asset for full details.
• get_asset — fetch one asset by its stable id (e.g. gradient.from-amber-200-to-yellow-500, pattern.top-gradient-radial, animation.scale-up-center).
• render_asset_code — render any asset as css/tailwind/react/tsx/svg/json.
• generate_gradient — generate a background gradient from colors or a mood. Warns if the result is AI slop (purple-to-blue).
• generate_text_gradient — generate clipped text gradient CSS. Always warns (gradient text is the #1 AI tell).
• generate_pattern_background — grid, dots, diagonal, waves, checker, radial, geometric patterns.
• get_animation_css — get a @keyframes animation with timing overrides (duration, delay, easing, iteration, direction, fill). Includes prefers-reduced-motion fallback.
• get_animated_icon — generate an animated icon component (lucide-react + motion) or a dependency-free inline SVG.
• generate_palette — generate a palette from a seed color or mood, with optional Tailwind mapping, CSS variables, and dark mode.
• map_color_to_tailwind — find the nearest Tailwind color(s) to any hex/rgb/hsl/named color.
• check_contrast — WCAG AA/AAA contrast check with accessible alternatives.
• generate_blob_svg — organic blob SVG with seeded determinism.
• generate_mesh_gradient — layered radial-gradient mesh.
• generate_glassmorphism — frosted-glass treatment (backdrop-filter, bg, border, shadow, radius).
• generate_box_shadow — soft/sharp/elevated/inner/neon/material shadows.
• compose_ui_treatment — the killer tool: compose a full hero/pricing/card/CTA/dashboard/etc. component from multiple generators, with token discipline, focus states, reduced-motion fallbacks, and overflow safety baked in.

Layer 2 — Knowledge & advisory (9 tools)

These tools give your agent design judgment, not just assets:

• recommend_design — given a product/audience/mood, returns a full design direction (palette, typography, motion, radius) with rationale, do/don'ts, and a11y notes. Grounded in curated recipes.
• critique_design — paste code or a description, get a structured critique: contrast failures (with exact alternatives), radius/shadow/hierarchy/a11y issues, plus the full 58-gate slop audit.
• slop_test — run the 58-gate anti-AI-slop audit on any HTML/CSS/JSX. Returns per-gate pass/fail/review, ranked findings with fixes, and a verdict (ships as slop / reads as AI-generated / clean).
• explain_concept — explain glassmorphism, mesh gradients, elevation, color harmony, text gradients, pattern backgrounds, CSS animation principles, or accessibility. Each with catalog examples.
• color_theory — all harmony schemes (complementary, analogous, triadic, split-complementary, tetradic, monochromatic) from a seed color.
• generate_design_system — full token system from one seed: 11-step brand scale, semantic colors, neutrals, radius/type/motion/elevation tokens, and component treatments. Output as CSS variables, Tailwind config, Style Dictionary, or Figma tokens.
• list_recipes / get_recipe / apply_recipe — 10 curated design recipes (premium-dark-saas-hero, fintech-trust-dashboard, playful-mobile-onboarding, devtools-landing, ai-product-hero, minimal-docs-site, creative-agency-portfolio, health-wellness-app, b2b-pricing-page, ecommerce-product-card). apply_recipe renders a production-ready component.
• study_design — paste HTML/CSS, extract the design DNA (palette, typography, macrostructure, slop flags) and get a portable design.md spec.
• pick_macrostructure — pick a categorically different page macrostructure, avoiding previously-used ones (variety rotation).
• recommend_assets_for — recommend concrete assets for an intent (e.g. 'background behind white text', 'card elevation') with computed affordances and reasons.

Layer 3 — Resources & prompts

Beyond tools, the MCP exposes resources (readable by URI) and prompts (workflow templates):

• Resources: gradientdeck://catalog/summary, gradientdeck://catalog/{kind}, gradientdeck://asset/{id}, gradientdeck://asset/{id}/{format}.
• Prompts: 9 workflow templates — design_hero, improve_component, theme_landing_page, create_dashboard_theme, create_empty_state, create_pricing_section, make_ui_more_premium, accessibility_pass, generate_brand_system.

Setup by agent

Pick your agent below. Every setup connects to the same endpoint. No auth, no token, no environment variable.

Claude Code (CLI)

Run one command in your terminal:

claude mcp add --transport http gradientdeck https://mcp.gradientdeck.com/mcp

Verify by typing /mcp inside Claude Code — you should see gradientdeck listed with 29 tools. If you want it available across all projects, add --scope user.

Alternatively, add it to .mcp.json (project-scoped, shareable via version control):

{
  "mcpServers": {
    "gradientdeck": {
      "type": "http",
      "url": "https://mcp.gradientdeck.com/mcp"
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "gradientdeck": {
      "url": "https://mcp.gradientdeck.com/mcp"
    }
  }
}

Cursor auto-detects Streamable HTTP from the URL. Restart Cursor or reload the window if the tools don't appear immediately. You can also add it via Settings → Cursor Settings → MCP → Add new MCP server.

Windsurf

Create or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gradientdeck": {
      "serverUrl": "https://mcp.gradientdeck.com/mcp"
    }
  }
}

Note: Windsurf uses serverUrl (not url). You can also add it via Settings → MCP Servers → Add.

OpenAI Codex (CLI / IDE)

Add to ~/.codex/config.toml:

[mcp_servers.gradientdeck]
url = "https://mcp.gradientdeck.com/mcp"

Codex reads configuration from ~/.codex/config.toml (user-level) or .codex/config.toml (project-scoped). The CLI and IDE extension share the same config layers.

OpenCode

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json for global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gradientdeck": {
      "type": "remote",
      "url": "https://mcp.gradientdeck.com/mcp",
      "enabled": true,
      "oauth": false
    }
  }
}

Verify with opencode mcp list. The oauth: false flag tells OpenCode not to attempt auth (GradientDeck is public/read-only).

Claude.ai (web / Desktop)

Go to Settings → Connectors → Add custom connector. Paste the URL. Leave authentication blank. The connector appears in your conversation tools.

OpenAI Responses API

For programmatic use via the OpenAI SDK:

import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [{
    type: "mcp",
    server_label: "gradientdeck",
    server_description: "GradientDeck design asset and CSS generator MCP server.",
    server_url: "https://mcp.gradientdeck.com/mcp",
    require_approval: "never",
  }],
  input: "Use GradientDeck to generate a premium dark SaaS hero background in Tailwind.",
});
console.log(response.output_text);

Verifying the connection

Every agent has a way to list connected MCP servers and their tools. After setup, verify:

• Claude Code: type /mcp — gradientdeck should show 29 tools.
• Cursor: check the MCP panel in Settings — gradientdeck should show as connected.
• Windsurf: Settings → MCP Servers — gradientdeck should show a green status.
• Codex: the tools appear in the agent's tool list automatically.
• OpenCode: run opencode mcp list — gradientdeck should show ✓ connected.
• Any client: curl the health endpoint — curl https://mcp.gradientdeck.com/health should return {"ok":true,...}

First things to try

Once connected, ask your agent to do something real. Here are examples that exercise different tool layers:

Browse the catalog

Ask your agent: "Use GradientDeck to list what asset kinds are available."

The agent calls list_asset_kinds and returns counts: 8,000+ gradients, 139 patterns, 662 animations, 154 icons, 7,900+ palettes, 228 Tailwind colors, 22 mesh presets, 11 shadows, 5 glass presets.

Get a design recommendation

Ask: "Use GradientDeck to recommend a design direction for a fintech dashboard for Gen Z."

The agent calls recommend_design, which matches the brief to a curated recipe (fintech-trust-dashboard), returns a full direction (palette, typography, motion, radius) with rationale for each choice, do/don'ts, and accessibility notes. It also suggests concrete assets and offers a brand-palette override if you provide a seed color.

Audit code for AI slop

Ask: "Use GradientDeck to audit this component for AI slop." and paste your code.

The agent calls slop_test, which runs the 58-gate audit. It flags purple-gradient heroes, gradient text, transition-all, hover:scale-105, bouncy easing, invented metrics, re-drawn chrome, missing prefers-reduced-motion, missing focus-visible states, and more — each with a concrete fix. The verdict tells you if the code 'ships as slop', 'reads as AI-generated', or is 'clean'.

Compose a full UI treatment

Ask: "Use GradientDeck to compose a premium dark SaaS hero in Tailwind."

The agent calls compose_ui_treatment with useCase 'hero'. The output is a production-ready React component with: a <style> token block (var(--gd-accent), etc.), :focus-visible/:active/:disabled states, @media (prefers-reduced-motion: reduce), overflow-x: clip, overflow-wrap: anywhere on headings, white-space: nowrap on buttons, a solid headline (no gradient text — gate 2), a left-biased layout (not full-viewport centered — gate 6), and a subtle accent radial (no multi-color mesh — gate 29). Every compose template passes the 58-gate slop test clean.

Generate a full design system

Ask: "Use GradientDeck to generate a design system from #14b8a6 in Tailwind config format."

The agent calls generate_design_system with seedColor '#14b8a6' and format 'tailwind'. You get an 11-step brand scale, semantic colors (success/warning/danger/info), neutrals, radius/typography/motion/elevation tokens, and component treatments (button, card, input, modal) — all in a tailwind.config.js you can paste directly.

The anti-slop system

GradientDeck MCP doesn't just hand you assets — it actively gates against AI-generated slop. This is what makes it different from every other design tool:

• Generators warn: generate_gradient detects purple-to-blue/cyan-to-magenta gradients (the #1 AI tell) and attaches prominent warnings with non-slop alternatives. generate_text_gradient always warns (no genre allows gradient text). generate_mesh_gradient warns on 4+ stacked radial-gradients (the aurora-blob default).
• compose_ui_treatment is clean by default: solid headline (no gradient text), single accent (no multi-color mesh), token discipline (var(--gd-*)), focus-visible/active/disabled states, prefers-reduced-motion, overflow-x: clip. All 10 templates pass the 58-gate test.
• slop_test audits any code: 58 gates adapted from the Hallmark design skill. ~30 are auto-checked with regex (purple gradients, transition-all, invented metrics, re-drawn chrome, missing reduced-motion, contrast failures, italic headers, aurora-blob mesh, emoji icons, and more). The rest are marked 'review' (they need rendering/context an MCP can't provide).
• critique_design integrates the slop test: paste code, get contrast failures + heuristic findings + the full 58-gate slop audit in one call.

Tips for getting the best results

1. Be specific about context: 'Recommend a design direction for a fintech dashboard for Gen Z' is better than 'make a landing page'. The recommend_design tool uses your product/audience/mood to match a curated recipe.
2. Always run slop_test after generating UI code: even if the generator warns, the slop test catches issues the generator can't self-check (e.g. contrast pairs, spacing scale, italic headers).
3. Use recipes: list_recipes shows 10 curated, opinionated design bundles. apply_recipe renders a production-ready component. These are the fastest path to non-slop output.
4. Provide a brand color: when calling recommend_design, compose_ui_treatment, or generate_design_system, pass brandColor to get a palette derived from your brand instead of a default.
5. Use check_contrast before shipping: paste your foreground and background colors, get the WCAG ratio and accessible alternatives. The critique_design tool does this automatically.
6. Mention 'use gradientdeck' in your prompts: some agents need the explicit nudge to prefer MCP tools over their built-in knowledge.

Limitations & what's coming

The MCP is a tool server, not a behavioral skill. It can check, warn, and generate — but it can't guide your agent through a design process (pre-flight scan, always-ask context gate, self-critique scoring). That's the skill layer's job, and it's coming soon.

Current limitations:

• ~28 of 58 slop gates are 'review' (manual) — they need rendering or file-system context that a stateless MCP can't provide.
• No URL/screenshot study — study_design accepts pasted HTML/CSS only (no live URL fetching, by security design).
• No state/memory — pick_macrostructure accepts client-provided history (the agent passes 'previous' macrostructures) instead of tracking automatically.
• No pre-emit 6-axis self-critique scoring (Philosophy/Hierarchy/Execution/Specificity/Restraint/Variety) — that requires model reasoning, which is the skill layer's job.

Health check & troubleshooting

The MCP has a health endpoint you can curl directly:

curl https://mcp.gradientdeck.com/health
# {"ok":true,"name":"gradientdeck-mcp","version":"0.1.0"}

If your agent can't connect:

• Verify the endpoint is up: curl the health endpoint above.
• Check that your client supports Streamable HTTP (not just stdio). GradientDeck is remote-only.
• Make sure you're not behind a firewall that blocks outbound HTTPS to mcp.gradientdeck.com.
• For OpenCode, set oauth: false to prevent auth attempts on a no-auth server.
• For Windsurf, use serverUrl (not url) — this is the most common config mistake.
• For Codex, ensure the TOML is valid (no quotes around the URL value in the [mcp_servers.gradientdeck] table).

GradientDeck MCP is free, public, and read-only. No accounts, no database, no user data stored. Connect once and start designing with your agent. Full setup instructions for every agent are at gradientdeck.com/mcp.