Endpoint
https://www.designesy.org/api/mcp
Transport
Streamable HTTP · POST · JSON or SSE response · stateless
Registry
io.github.LE-VAI/designesy-org v1.3.1 on registry.modelcontextprotocol.io
Published on the MCP Registry
Discoverable by any MCP-compatible client. Search designesy on the registry or connect directly.
Conformance
WCAG 2.2 AA
0 violations
axe-core 4.13.0 · wcag22aa · pinned to current npm latest (verified 2026-08-30 via registry check)
DTCG 2025.10
90% A
/export/dtcg · 9/10 checks pass · 1 WARN (custom types non-standard, namespaced designesy.* per t07) · verified 2026-08-30
Contract score
93% A
42-check engine · 38 PASS / 0 FAIL / 0 WARN / 1 SKIP / 3 MANUAL
Tools
Seven read-only tools fetch public machine exports from designesy.org. Nine executable tools run live verification — the 42-check score engine, DTCG token validation, Lottie motion validation, drift scoring, AI-readiness scoring, guardrails generation, monitor scoring, design-system comparison, and the composite report. One accessibility framework provides the WCAG 2.2 Playwright + axe-core script template. All tools return JSON.
01designesy_catalog Read-onlyThe full package catalog — 23 published packages (contracts, kits, labs, reviews, tools) with versions, URLs, statuses, standing rules, and machine exports.args: nonesource: /open.json 02designesy_contract Read-onlyThe design-system contract v0.4.0 — tokens, motion, acoustic, takt, cadence, typography, components, verification, open tensions. Optional section filter.args: section?: stringsource: /contracts/design-system.json 03designesy_design_review Read-onlyThe Design Review kit — 8 dimensions, agent prompt, output format, verification checklist. Optionally pre-fills the prompt with artifact, purpose, context, rules.args: artifact?, purpose?, context?, rules?source: /kits/design-review.json 04designesy_skill_md Read-onlyThe SKILL.md agent-skill export of the contract — behavioral rules, tokens, anti-patterns, and verification in paste-ready markdown.args: nonesource: /contracts/skill 05designesy_agent_json Read-onlyThe /.well-known/agent.json discovery document — identity, authority, ingest protocol, packages, machine exports, permission policy, cite templates.args: nonesource: /.well-known/agent.json 06designesy_llms_txt Read-onlyThe short agent-facing brief — canonical reference, topics, ingest steps, package list, contact. Returns text/plain.args: nonesource: /llms.txt 07designesy_llms_full_txt Read-onlyThe full agent-facing brief — ingest protocol, discovery endpoints, all packages, standing rules, anti-patterns, and the complete paste-ready agent prompt. Returns text/plain.args: nonesource: /llms-full.txt 08designesy_score ExecutableThe 42-check verification engine. Fetches the page HTML, extracts all CSS, parses :root custom properties, and runs 42 automated checks with provenance back to contract tokens. Returns overall score, letter grade, and per-check breakdown. Browser-only checks (Core Web Vitals, viewport overflow, sound toggle) return MANUAL — run the full audit (/api/score/audit) to resolve them. Checks that are not applicable to the site (no tokens, no buttons, no DESIGN.md) return SKIP (N/A).args: url?: string (defaults to designesy.org)source: /api/score 09designesy_tokens_score ExecutableValidate a design token file against W3C DTCG 2025.10 format. Fetches from a URL or accepts raw JSON. Runs 10 conformance checks (t01-t10): $schema, token groups, $type, $value, structured color format, standard types, custom extensions, dimension units, naming hierarchy, deprecated patterns. Returns score, grade, and per-check breakdown.args: url?: string, dtcg_file?: stringsource: /contracts/tokens.json 10designesy_a11y_score FrameworkAccessibility verification framework for WCAG 2.2 AA via axe-core 4.13.0. Returns 11 conformance checks (a01-a11) + a Playwright script template (axe-core needs a real DOM, cannot run server-side). The agent runs the script locally with @axe-core/playwright. Optional config JSON enables brand customization via axe.configure().args: url: string, ruleset?: string, config?: stringsource: /contracts/a11y.json 11designesy_motion_score ExecutableValidate a Lottie animation file against Lottie spec v1.0.1 and Designesy section 16 Ten Non-Negotiable Motion Standards. Fetches from a URL or accepts raw JSON. Runs 10 checks (m01-m10): required fields, version, frame rate, dimensions, layers, in/out points, markers for reduced-motion, deprecated layers, section 16 standards, JSON Schema conformance.args: url?: string, lottie_file?: stringsource: /contracts/motion.json 12designesy_drift_score ExecutableScore a live URL for AI-generated UI drift — 12 checks detect the four documented 2026 drift failure modes: token fabrication (var() to undeclared custom properties), within-session drift (spacing/color/radius value variance), between-session amnesia (inconsistent font stacks, shadows, transitions), and silent breaking changes (z-index chaos, dangling alias chains). Fetches the URL, extracts all CSS, parses :root tokens and var() references.args: url?: string (defaults to designesy.org)source: /api/drift 13designesy_readiness_score ExecutableScore a URL for design-system AI readiness — the 6th maturity axis (zeroheight 2026). 10 checks probe the target origin for machine-readable artifacts: DTCG token files, llms.txt, agent.json, MCP endpoint (tools/list), DESIGN.md, token $description, component schemas, sitemap.xml, robots.txt, and Open Graph/Twitter meta.args: url?: string (defaults to designesy.org)source: /api/readiness 14designesy_guardrails ExecutableGenerate a frozen build-contract bundle for AI coding agents from any design system URL — the product layer. Ingests a site, extracts its :root tokens, and emits 6 outputs: DTCG-format token file, Stylelint config, AGENTS.md rules, component contract, anti-pattern documentation, and DESIGN.md (Google open spec). 6 emission checks verify bundle completeness.args: url?: string (defaults to designesy.org)source: /api/guardrails 15designesy_monitor_score ExecutableScore a URL for continuous design-drift governance — the temporal layer over the drift radar. Re-runs the 12 drift checks and computes 10 monitor checks: schedule registered, last run fresh, drift delta vs baseline, trend slope, new violations, resolved since last run, score degradation threshold, token-set mutation, contract version drift, and alert delivered. When alerts fire and an email is provided, sends an HTML drift-alert email via Resend. Pass a history array of prior snapshots to compute deltas.args: url?: string, email?: string (for drift alerts), history?: Snapshot[] (omit for first-run baseline)source: /api/monitor 16designesy_compare ExecutableDiff two design systems from live URLs — the only URL-scoped design-token diff engine. Fetches both URLs in parallel, extracts their :root custom properties, and produces a structured diff across 8 dimensions: tokens added, removed, renamed (Levenshtein ≤ 2), value-changed, scale-stop-changed, contrast-drift-per-pair (WCAG ratio), structure-delta (token count + category distribution), and score-delta (runs /score on both URLs). Use this to answer "what actually changed between two design systems" or "how does our design system differ from a reference".args: urlA: string (first URL), urlB: string (second URL)source: /api/compare 17designesy_report Executable · MCP AppGenerate a unified design-intelligence report for a single URL — the synthesis capstone. Fires /score (42-check audit), /drift (12-check drift radar), and /readiness (10-check AI readiness) in parallel, then computes a weighted composite: score × 0.5 + drift × 0.3 + readiness × 0.2. One input, one output, one composite grade. Use this when you need a single holistic assessment instead of three separate scans, or when sharing a design-intelligence verdict. MCP App: hosts that support io.modelcontextprotocol/ui (Claude Desktop, Cursor v2.6+, VS Code, Goose) render an interactive dashboard inline — composite dial, sub-engine cards, tabbed check breakdown. Legacy clients get the JSON payload plus an appUrl link to the standalone dashboard.args: url: stringsource: /api/report + /api/report/app Client configuration
Copy-paste the config for your client. Most modern clients support Streamable HTTP natively — just point them at the endpoint. For stdio-only clients, use the mcp-remote bridge.
Claude Code (CLI)
~/.claude.json or ~/.claude/settings.json
{
"mcpServers": {
"designesy": {
"type": "http",
"url": "https://www.designesy.org/api/mcp"
}
}
}Claude Code (the CLI agent) supports Streamable HTTP natively via type: "http". This is separate from Claude Desktop (below).
Cursor
.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
"mcpServers": {
"designesy": {
"url": "https://www.designesy.org/api/mcp"
}
}
}Cursor supports Streamable HTTP directly — just provide url. It auto-detects HTTP vs SSE. No type field needed.
ZCode
.zcode MCP config (User or Workspace scope)
{
"mcpServers": {
"designesy": {
"url": "https://www.designesy.org/api/mcp"
}
}
}ZCode supports HTTP, SSE, and stdio. Add via Settings → MCP Servers (type: HTTP), or paste this JSON in full config mode.
VS Code + Copilot
.vscode/mcp.json
{
"servers": {
"designesy": {
"type": "http",
"url": "https://www.designesy.org/api/mcp"
}
}
}VS Code with GitHub Copilot supports HTTP MCP servers. Note: key is "servers", not "mcpServers". VS Code tries HTTP Stream first, falls back to SSE.
Claude Desktop (stdio-only — needs mcp-remote bridge)
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"designesy": {
"command": "npx",
"args": ["mcp-remote@latest", "https://www.designesy.org/api/mcp"]
}
}
}Claude Desktop's JSON config is stdio-only — a url field silently deletes the entire mcpServers block (bug #37286). Use the mcp-remote npm package as a stdio bridge. Alternatively, add the server via Settings → Connectors → Add custom connector (no JSON editing, supports public HTTPS directly).
How it works
Runtime
Vercel Node.js serverless · mcp-handler 2.x (Vercel's official MCP adapter) · @modelcontextprotocol/server (SDK v2) · Zod 4 · stateless 2026-07-28 spec native · 300-second max duration (Pro Plan)
Caching
5-minute in-memory cache on read-only tools. Vercel Fluid Compute reuses warm instances, so cache hits are common. The executable tool (designesy_score) is never cached — every score request hits the live engine.
No Python
The server is native TypeScript. It runs in the same Vercel runtime as this site — no child processes, no mcp-proxy bridge, no external dependencies beyond the MCP SDK.
The seven read-only tools fetch the same public machine exports that any HTTP client can fetch directly. The MCP server adds structured tool schemas, Zod validation, and a single authenticated endpoint — useful for agents that prefer the MCP protocol over raw HTTP.
Quick test
Verify the endpoint is live with a single curl:
curl -X POST https://www.designesy.org/api/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'The response is a JSON-RPC 2.0 message listing all seventeen tools with their schemas.
The MCP server is a native integration surface — no wrapper, no proxy, no Python. It is the same design intelligence, available to any agent that speaks the protocol.