Mozaic MCP Server

MCP server and agent skills for the Mozaic Design System by ADEO, for any coding agent: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, ...

📚 Documentation • 🎮 MCP Playground • 🌐 Website

Overview

This package provides two complementary tools for working with the Mozaic Design System in coding agents:

• 🤖 Agent Skills - 8 interactive skills for guided component building and design token usage
• 🔌 MCP Server - Model Context Protocol server with 19 tools for programmatic access to Mozaic resources

HTTP API

Coding agents should use the local stdio server (npx -y mozaic-mcp-server@2, see Quick Start). The HTTP API is a separate, token-protected server for web tools (e.g. v0) that cannot spawn a local process.

Public server: https://mozaic-mcp.m14i.com (Swagger)

Full vs light: the full endpoints proxy to a spawned stdio MCP server and expose all 19 tools. The light endpoints read SQLite directly (no subprocess, faster) and expose 7 tools: get_design_tokens, list_css_utilities, get_css_utility, search_icons, get_icon, list_style_guides, get_style_guide (get_style_guide returns the screenshot as a PNG image block).

Authentication: Authorization: Bearer <token> on every route except /health and /api. Contact me on Slack for a token.

Call a tool: body is {"name": "<tool>", "arguments": {...}}.

curl -X POST https://mozaic-mcp.m14i.com/mcp/light/call-tool \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"search_icons","arguments":{"query":"arrow","limit":5}}'

Self-hosting env vars: PORT (3000), AUTH_TOKEN, DATABASE_PATH (/app/data/mozaic.db), MCP_SERVER_PATH (/app/dist/index.js), MCP_DEBUG. See DEPLOYMENT.md.

What's Included

Quick Start

Works with any coding agent that supports Agent Skills and/or MCP: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, VS Code, ...

Install

Two standard, agent-agnostic CLIs. Each detects your agents and writes to the current project by default:

npx skills add MerzoukeMansouri/adeo-mozaic-mcp        # 8 skills -> .agents/skills/, .claude/skills/, ...
npx add-mcp mozaic-mcp-server@2 --name mozaic           # MCP server -> .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml, ...

• npx skills and npx add-mcp both accept -g (your user instead of the project), -a <agent> (target specific agents) and -y (no prompts).
• The skills' scripts install their database (~/.mozaic/mozaic.db) on first use. Refresh it any time with npx -y -p mozaic-mcp-server@2 mozaic-db.
• Remove: npx skills remove <skill> and npx add-mcp remove mozaic.

Project or global?

• Project (default, recommended): commit the generated files so the whole team gets the same setup, and skills are only loaded in Mozaic projects.
• Global (-g): for your user across every project, nothing to commit.
• Never npm i -g: agents run the server with npx -y mozaic-mcp-server@2, which stays on major version 2 and picks up fixes.

Try Before Installing

Test all 19 MCP tools directly in your browser, without installation:

🎮 Open MCP Playground

Agent Skills

8 skills that provide interactive workflows for building with Mozaic.

Available Skills

How Skills Work

Skills follow the Agent Skills format (skills/<name>/SKILL.md), so any compatible agent activates them automatically based on context:

User: "I need a login form with Mozaic"

The agent activates the appropriate skill (e.g. Vue or React builder) and guides you through:

1. Component selection
2. Props configuration
3. Code generation
4. Installation instructions

See SKILLS.md for detailed documentation.

MCP Server Tools

19 programmatic tools for accessing Mozaic resources via the Model Context Protocol.

Available Tools

Configuration

npx add-mcp mozaic-mcp-server@2 --name mozaic writes the right file for each agent. The server name must be mozaic (the mozaic-style-guide skill expects it). Manual setup, for example .mcp.json (Claude Code) or .cursor/mcp.json (Cursor):

{
  "mcpServers": {
    "mozaic": {
      "command": "npx",
      "args": ["-y", "mozaic-mcp-server@2"]
    }
  }
}

VS Code uses a servers key in .vscode/mcp.json; Codex uses [mcp_servers.mozaic] in .codex/config.toml.

The server is also published to the MCP Registry as io.github.MerzoukeMansouri/mozaic.

Usage Examples

Using Skills

Skills activate automatically based on your request:

You: "I need a responsive grid with 3 columns"
Agent: [activates mozaic-css-utilities skill]
        Here's the Flexy grid solution...

You: "Add a shopping cart icon"
Agent: [activates mozaic-icons skill]
        I found these cart icons...

Using MCP Tools Programmatically