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.
What is MCP
Section titled “What is MCP”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 standalonemzizi-mcpCloudflare Worker fromnyuchi/mzizi-tools, a registry-driven surface with a much wider tool catalog (~60 tools loaded from themcp_tool_registrytable) behind a free Connect OAuth signup gate.
Endpoint
Section titled “Endpoint”The MCP server is served at /mcp via Streamable HTTP transport:
POST https://mzizi.dev/mcp — JSON-RPC requestsGET https://mzizi.dev/mcp — SSE streamDELETE https://mzizi.dev/mcp — cleanupOPTIONS https://mzizi.dev/mcp — CORS preflightConfiguration
Section titled “Configuration”Claude Code
Section titled “Claude Code”Add to .claude/settings.json:
{ "mcpServers": { "mzizi": { "type": "url", "url": "https://mzizi.dev/mcp" } }}Other MCP clients
Section titled “Other MCP clients”Any MCP-compatible client can connect using the Streamable HTTP transport at https://mzizi.dev/mcp.
Resources
Section titled “Resources”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
Section titled “list_components”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.
get_component
Section titled “get_component”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_collections
Section titled “list_collections”List the per-node collections with total counts and ownership breakdown. No arguments.
Returns: One entry per collection with total and byOwner counts.
get_database_status
Section titled “get_database_status”Diagnostic info — Supabase connection health and document-store row count. No arguments.
Architecture
Section titled “Architecture”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 definedapp/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.
Use cases
Section titled “Use cases”Building a new bundu ecosystem app
Section titled “Building a new bundu ecosystem app”An AI assistant can use the MCP server to:
- Call
list_collectionsto see what the registry holds per node - Call
list_componentsfiltered to the node it is building against (N2 primitives, N3 brand) - Fetch full component documents with
get_componentand install via the shadcn CLI againstmzizi.dev/api/v1/ui/<name>
Code review
Section titled “Code review”During PR review, the AI assistant can:
- Verify components use the correct design tokens
- Check that new components follow the CVA + Radix + cn() pattern
- Validate accessibility compliance against Mzizi standards