@zaai-dev/mcp

Zaai Dev MCP

Model Context Protocol server for the Zaai Dev platform. Exposes your captured design references to MCP-compatible AI tools — Claude Code, Claude Desktop, Cursor, Continue, Cline, anything else that speaks MCP.

After a one-time token paste, prompts like "list my last 5 captures tagged hero and show me their palettes" call the workspace directly and pull back real data.

Install

You need:

• Node 20 or newer (node --version)
• A Zaai Dev workspace account at https://www.zaaistudio.com
• An MCP token — mint one at https://www.zaaistudio.com/dev/settings/tokens (pick "mcp" as the kind). The token-mint screen also shows the config snippets below pre-filled with your secret.

Claude Desktop

Add to claude_desktop_config.json — merge into the existing mcpServers block, don't replace the whole file.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "zaai-dev": {
      "command": "npx",
      "args": ["-y", "@zaai-dev/mcp"],
      "env": {
        "ZAAI_API_TOKEN": "zaai_mcp_YOUR_SECRET_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 9 tools below appear in the slash-command picker.

Cursor

Add to ~/.cursor/mcp.json — same JSON shape as Claude Desktop.

{
  "mcpServers": {
    "zaai-dev": {
      "command": "npx",
      "args": ["-y", "@zaai-dev/mcp"],
      "env": {
        "ZAAI_API_TOKEN": "zaai_mcp_YOUR_SECRET_HERE"
      }
    }
  }
}

Restart Cursor.

Claude Code (CLI)

One-liner — updates ~/.claude/mcp_servers.json automatically:

claude mcp add zaai-dev -e ZAAI_API_TOKEN=zaai_mcp_YOUR_SECRET_HERE -- npx -y @zaai-dev/mcp

Tools

All tools except health need a valid token. All tools except health and whoami charge 1 credit per successful call (your workspace plan determines the monthly credit grant — see pricing).

Tool	What it does
health	Server status + version + uptime. No auth, no charge.
whoami	Returns your userId, orgId, project scope, and credit balance. No charge.
list_captures	Paginated list of your captures (newest first). Args: q, cursor, limit.
search_captures	Same as list but with q required. Tuned description for targeted retrieval.
get_capture	Full payload + signed screenshot URLs for one capture id.
get_palette	Just the palette slice (page) or eyedropper picks (element/composite).
get_html	Just the HTML. Page → full HTML; element → outerHTML; composite → concat with markers.
get_animation	Just the animation data — CSS transitions, keyframes, library hints.
get_media	Just the media inventory — videos, images, backgrounds, carousels.

Plus the zaai-capture://{id} resource template — attach individual captures to a conversation via the resource picker.

Errors

Error class	Meaning	Action
Unauthorized	Token invalid, revoked, or wrong kind	Mint a fresh mcp token, update your config, restart
InsufficientCredits	Out of credits for the month	Top up or wait for the monthly grant
CaptureNotFound	id doesn't exist OR is in a project the token can't see	list_captures to find valid ids
InvalidCaptureId	id isn't a UUID	Pass an id from list_captures or the workspace URL
UnknownCaptureField	Hit a focused-getter route with an unknown field	Use one of: palette, html, animation, media

Errors return as isError: true in the tool result so the LLM can read and act on them.

Privacy + scoping

The server holds only your MCP token — it never sees your password, your Supabase service-role key, or other users' data. The workspace's verifyToken derives userId + orgId from your token on every request; queries are scoped to that user + the token's project allowlist (which you set at mint time). A revoked token causes the next tool call to fail with Unauthorized.

The server itself runs entirely on your machine — npx -y @zaai-dev/mcp downloads the package once, then your AI tool launches it as a subprocess. No telemetry, no analytics SDK.

Building locally

git clone https://github.com/POLONIBOI/ZAAI_dev_mcp.git
cd ZAAI_dev_mcp
pnpm install
pnpm build
pnpm inspector            # MCP Inspector for interactive testing

You'll need ZAAI_API_TOKEN set as an env var (or pasted into the Inspector's Environment Variables panel before clicking Connect).

License

MIT.