Integration surface

MCP server

Designesy design intelligence over the Model Context Protocol — eight tools, one endpoint, no wrapper.

The Designesy MCP server runs natively on the same Vercel project as this site. It speaks the 2026-07-28 Streamable HTTP spec — stateless, no sessions, no handshake. Any MCP-compatible client can connect.

Endpoint

https://www.designesy.org/api/mcp

Transport

Streamable HTTP · POST · JSON or SSE response · stateless

Registry

org.designesy.www/designesy v1.2.0 on registry.modelcontextprotocol.io

Tools

Seven read-only tools fetch public machine exports from designesy.org with a 5-minute in-memory cache. One executable tool runs the 34-check verification engine against any live URL. All tools return JSON.

01designesy_catalog Read-onlyThe full package catalog — 12 published packages (contracts, kits, labs, reviews) with versions, URLs, statuses, standing rules, and machine exports.args: nonesource: /open.json

02designesy_contract Read-onlyThe design-system contract v0.3.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 34-check verification engine. Fetches the page HTML, extracts all CSS, parses :root custom properties, and runs 23+ 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 SKIP.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.12.1. 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

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 (Vercel's official MCP adapter) · @modelcontextprotocol/sdk · Zod schemas · 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 eight tools with their schemas.

01Docs · orientationMission, principles, architecture, public voice 02Open design intelligenceHuman index and machine feed of portable packages 03open.jsonMachine catalog — the same data the MCP server serves 04Design system contractv0.3.0 — the contract behind designesy_contract

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.