Skip to content

MCP Server

The Mzizi portal includes a Model Context Protocol (MCP) server that exposes the registry, brand system, and design tokens to AI assistants. This enables tools like Claude Code to understand and work with the Mzizi design system natively.

The Model Context Protocol is an open standard for connecting AI assistants to external data sources and tools. It allows AI assistants to:

  • Read structured data (components, tokens, guidelines)
  • Call tools (list collections, fetch full component documents)
  • Stay current — the MCP server always reflects the latest registry state

Two MCP surfaces read the same document store:

  • https://mzizi.dev/mcp — the canonical document-route MCP served by the portal (described on this page).
  • https://mcp.mzizi.dev/mcp — the standalone mzizi-mcp Cloudflare Worker from nyuchi/mzizi-tools, a registry-driven surface with a much wider tool catalog (~60 tools loaded from the mcp_tool_registry table) behind a free Connect OAuth signup gate.

The MCP server is served at /mcp via Streamable HTTP transport:

POST https://mzizi.dev/mcp — JSON-RPC requests
GET https://mzizi.dev/mcp — SSE stream
DELETE https://mzizi.dev/mcp — cleanup
OPTIONS https://mzizi.dev/mcp — CORS preflight

Add to .claude/settings.json:

{
"mcpServers": {
"mzizi": {
"type": "url",
"url": "https://mzizi.dev/mcp"
}
}
}

Any MCP-compatible client can connect using the Streamable HTTP transport at https://mzizi.dev/mcp.

Resources are read-only data that AI assistants can access:

URI Description
mzizi://components Component registry index — one row per document (name / node / collection / owner)
mzizi://nodes Per-node collection summary — counts and ownership breakdown across all 10 nodes

Tools are callable actions the AI assistant can invoke:

List components from the document store, optionally filtered by node (1–10) or owner (bundu / nyuchi / mzizi / framework). Returns the lean index; use get_component for the full document.

{ "node": 2, "owner": "mzizi" }

Returns: Array of { name, node, collection, owner } rows.

Fetch one component as its full JSON document — one read, everything in it (metadata, owner, sources/descriptors, legacy source code, files, docs).

{ "name": "button" }

Returns: The complete component document.

List the per-node collections with total counts and ownership breakdown. No arguments.

Returns: One entry per collection with total and byOwner counts.

Diagnostic info — Supabase connection health and document-store row count. No arguments.

The MCP server is implemented in two files in nyuchi/mzizi (the design-portal repo):

  • lib/mcp-server.ts — server factory (createMziziMcpServer(supabase)) with all tools and resources defined
  • app/mcp/route.ts — HTTP endpoint (Streamable HTTP transport)

The server reads exclusively from the Supabase component_documents table — one self-contained JSON document per component, keyed by node collection. Reads are anon-scoped and RLS-enforced; there is no write surface.

An AI assistant can use the MCP server to:

  1. Call list_collections to see what the registry holds per node
  2. Call list_components filtered to the node it is building against (N2 primitives, N3 brand)
  3. Fetch full component documents with get_component and install via the shadcn CLI against mzizi.dev/api/v1/ui/<name>

During PR review, the AI assistant can:

  1. Verify components use the correct design tokens
  2. Check that new components follow the CVA + Radix + cn() pattern
  3. Validate accessibility compliance against Mzizi standards