Design system MCP server vs DESIGN.md: you need both, in layers

The MCP-or-file debate assumes one source of guidance. Small teams actually have two: their own system and the practice nobody wrote down. The file holds one; the server delivers both.

The short answer

Use both, for different jobs. DESIGN.md holds your system: your tokens, your visual language, your voice, the reasons behind each call. An MCP server delivers UX guidance on demand to every agent and teammate in the tools they already use. For a small team, the split is clean: your system lives in DESIGN.md, a shared base layer of UX practice runs through the MCP, and your layer sits on top.

Where DESIGN.md stops

DESIGN.md holds your values and your reasons. It doesn't hold how to design an empty state, when to confirm a destructive action, how to write an error message, or how to lay out a settings page. That's practice, not brand. Agents fill those gaps with generic defaults, and the defaults are weak.

Your file defines your button color. It doesn't say one primary button per section. Your file names your tone of voice. It doesn't say what a form validation error sounds like at 11pm when a user just lost their work.

On a client's product redesign, we built the full system through working prototypes. We still had to add rules a design system doesn't cover, like one primary button per section and when to use a modal vs a drawer, so a client with a 10-developer team built to one standard.

The gap isn't a failure of your DESIGN.md. It's the gap between brand and craft. Much of that craft shows up in agent UX work: empty states, confirmations, and error copy agents get wrong when nothing tells them otherwise.

Two layers, one source

The base layer is what a design partner brings: UX patterns, content and microcopy rules, layout conventions, product strategy prompts. It applies across every client. We keep it current and versioned.

Your client layer is your DESIGN.md: your tokens, your visual language, your voice, your components, your do's and don'ts. It lives in your repo. You own it. The AI-ready design systems series is how we structure that client layer in the repo.

One MCP serves both. The server delivers the base layer and reads your client layer on top. When they conflict, your layer wins.

What goes in each layer

Which file inside your repo holds your client layer is a separate question. AGENTS.md vs DESIGN.md vs SKILL.md sorts that.

When they disagree

Your client layer overrides. The base layer defers to any explicit instruction in your client file. If your DESIGN.md says a confirmation modal appears before delete, that call stands regardless of what the base layer suggests. The base layer fills in gaps. It doesn't overwrite decisions you've already made.

Why deliver the base layer through an MCP

Rules written down once still drift across 10 developers unless every agent pulls the same version. That's the core problem.

A guide nobody queries doesn't govern anything. Pasting a base layer into every repo means every repo drifts from the moment someone updates one and not the others. A new agent doesn't know which version is current. A new teammate doesn't know where to look.

An MCP closes this cleanly. Every agent and teammate in Claude Code and Cursor pulls the same approved version. No manual copying. Updates arrive without a PR in each repo. Keep the tool surface small so agents actually call it.

One honest caveat: an agent that thinks it already knows a pattern won't query the server. That's why DESIGN.md and AGENTS.md still point the agent at the server explicitly. The MCP isn't autonomous. It needs a prompt chain that sends agents to it, and those files do that work. Claude Code design skills is the install path when you want repeatable procedures on top of the same sources.

Changelog and sign-off

Nothing reaches agents unreviewed.

Every change to either layer gets a changelog entry and a named approver. The MCP serves only the approved version. This isn't overhead. It's how you compound trust in the system over time. When a developer or agent follows the guidance and it's wrong, you have a named approver to revisit. When it's right, you have a record of why the call was made.

designgov.md holds the governance contract above your file. AI UI brand governance is the process for keeping the package current once agents are shipping UI.

Drift kills systems. Changelog and sign-off lock them in.

Do you need to build your own server?

Usually not.

If you build on a large open-source component library that ships its own CLI or server, use it for component APIs. That server exists for component documentation. You still need your client layer and the base practice layer on top of it.

Three realistic paths for a small team:

DESIGN.md only. One product, simple UI, someone with real design judgment in the loop at every PR. This works until agents make enough weak calls that you're fixing them in review every week.

DESIGN.md plus a partner-run base layer over MCP. You're shipping fast with agents and you don't have a full-time designer. The base layer handles practice; your DESIGN.md handles brand. This is the setup we build for teams.

A full internal server. You have a platform team and a large private component library. You build and host your own server. Right call at scale. Not the right starting point.

What we set up, and what it costs

As a fractional design engineer and design partner, we set this up and build it for your team.

A two-week Sprint at $3,750 covers writing or cleaning up your DESIGN.md, building the base layer for your team, and wiring the MCP into your team's tools. At the end, every agent and teammate in Claude Code and Cursor pulls from the same approved source. When the scope is a full AI-ready system build, we run the same layering inside that project.

After the Sprint, a monthly plan keeps both layers current with changelog and sign-off: Standard at $4,995/mo or Advanced at $7,495/mo. Advanced is double the capacity with availability for check-ins as required. Published prices are on pricing: a Sprint is $3,750 per two weeks, Standard is $4,995 a month, and Advanced is $7,495 a month.

Changes are reviewed and named before they reach your agents. The system compounds because the foundation doesn't drift.