Milda & AI - the MCP server

@mildastudio/mcp exposes a published Milda design system to AI coding agents over the Model Context Protocol. An agent can discover your components, read their exact contracts, pull design tokens, generate real source, and check breaking changes - so it never guesses a prop name. This is the “AI speaks Milda” surface.

#Why this matters

AI coding agents are good at producing UI, but left to themselves they invent props, restyle from scratch, and drift from your system. Milda already holds the single source of truth - the IR, the typed contracts, the tokens. The MCP server projects that truth into the agent's context, so the code it writes is on-system by construction: real component names, exact prop types, your tokens instead of hard-coded values.

It is a thin, read-oriented projection over data you already have - no new modeling. A project is queryable only once it is published; publishing is the gate.

#The tools it exposes

Tools are the actions an agent calls. Every handler reads the same loaded document, so answers reflect the exact, current contract.

list_components - list every component with its archetype and description.
search_components - find components by free-text query (matched against name, archetype, description). The agent runs this before building UI to discover what already exists.
get_component - the exact contract of one component: props (with types, required, defaults), events, and composition slots. Called before writing code so prop names and types are never guessed.
list_tokens - foundation tokens, optionally filtered by type (e.g. color, spacing, radius).
generate_component_code - real, self-contained source for one component in the requested target (react today), including the shared theme. These are the actual files the release pipeline would publish.
get_install_command - the npm install line for the released package, pinned to the latest version and the public registry.
diff_contract - changes versus the last published release, the resulting semver severity, and the version it would bump to. Used to understand breaking changes before upgrading.
get_docs - the authored documentation pages: without an argument it lists pages; with a page id it returns that page as markdown.
get_source - the whole design system as a .milda file. Every other tool here answers one question; this one hands over the system itself - foundations, every component with its anatomy and behaviour, the library organisation, the demo scenes, the asset library and the docs - in a format the agent can also write when it proposes a change.

#Resources and prompts

Alongside tools, the server publishes addressable resources - milda://library (overview: package name, released version, component roster), milda://components/{name}(one component's contract as markdown), milda://foundations/tokens (every token), and milda://source (the whole system as a .milda file - the same text get_source returns). Two prompts prime the agent: build_with_milda (discover components, then read their contracts before writing code) and plan_release_migration (summarize pending contract changes and draft a migration).

#Running it

The server is transport-agnostic and serves a single project scope (an org and project). It reads Supabase credentials from the environment; copy .env.example to .env and fill in the Supabase service credentials before running.

#Local (stdio) - for Claude Code / Cursor

The stdio transport is what a local MCP client launches directly. The scope comes from MILDA_ORG and MILDA_PROJECT:

bash

MILDA_ORG=<org-slug> MILDA_PROJECT=<project-slug> npm run stdio -w @mildastudio/mcp

bash

claude mcp add milda \
  --env SUPABASE_URL=... --env SUPABASE_SERVICE_ROLE_KEY=... \
  --env MILDA_ORG=<org-slug> --env MILDA_PROJECT=<project-slug> \
  -- npx tsx apps/mcp/src/stdio.ts

#Hosted (streamable HTTP) - mcp.milda.dev

The HTTP transport lets one deployment serve every org and project: the scope comes from the URL path, and the auth token from the Authorization header. Run it locally on :6457:

bash

npm run dev -w @mildastudio/mcp

A client points at the scoped URL:

text

POST https://mcp.milda.dev/<orgSlug>/<projectSlug>
Authorization: Bearer <docs API token>

Access model

A project is queryable only once published - publishing is the gate. Public projects need no auth; private projects require a docs API token, the same token the docs read API uses.

For how a system gets published in the first place, see Build your first design system and Release & registry.