Documentation.

Zaklad exposes a Model Context Protocol (MCP) server, a standard interface that lets any MCP-compatible AI tool read and write your design system over a structured API. MCP clients include Claude, Cursor, Copilot, and any tool that supports the open protocol.

Crucially, this is a two-way interface. An AI can read the current state of your tokens, typography, components, and themes, and it can change them too: create and edit tokens, restructure components, build themes, regenerate palettes. It is not a static file an AI reads once; it is a connected endpoint that both reflects and updates the live system.

With a Read + Write token, an AI does not just read your system, it maintains it. Describe a change in plain language and the AI calls the write tools to apply it directly to the live system: creating and editing tokens, restructuring components, building themes, regenerating palettes. No manual editing in the dashboard required.

Every write is governed the same way a human edit is. Changes run through the same validation the editor enforces, each lands as a single undoable change set, and locks are respected: an AI can never modify a token group, text style, or component you have locked. The recent AI activity panel in Settings logs every change with a full before and after, and you can revoke a token at any time. Issue a read-only token when you want querying with no risk of edits.

See the tool reference for everything an AI can read and change, and the practical examples below for end-to-end editing prompts.

The server is self-documenting in two ways. First, any connected client can call get_capabilities (or the standard tools/list) to discover every tool it can use, so an AI configures itself the moment it connects.

Second, the product documentation you are reading right now is available over the same connection. search_docs runs a free-text search across these docs and returns the most relevant sections; get_doc returns a full section as Markdown; and list_docs lists every topic. Each result carries a deep link back to the page here, so an AI can answer a 'how do I…' question and point you straight to the source.

This means you can treat the MCP connection as a way to ask how to use Zaklad, not only as a way to read and edit your tokens. Ask your assistant how themes inherit, how to switch themes in code, or how colours resolve, and it answers from the live documentation rather than guessing.

Colours resolve through a chain: a component token points at a semantic token (a named slot like color.container.brand.weak), and each theme overrides that slot with a specific foundation colour. The theme override is what actually renders. The semantic token only names the slot; its own default value is just a fallback for themes that have no override.

The practical consequence: to change a colour, an AI must set the per-theme override, not the semantic token's default. Editing the semantic default alone looks like it worked but changes nothing on screen, because every theme already overrides that slot. The update_theme_override tool is the write that changes colours; update_token is for non-colour values (spacing, type, fonts), foundation colours, and metadata.

Each theme is set independently, so Light and Dark usually take different foundation steps (a light step for Light, a darker one for Dark). Themes also inherit: Dark typically inherits from Light and only overrides what differs, so a token can read as “inherited” in one theme and explicitly overridden in another. get_theme shows both the current value and whether it is inherited or overridden for every token.

The MCP server is useful even without active AI generation. It means your design system data lives in one place with a clean API: version-controlled, audited, and accessible to any tool that supports MCP.

Teams use it to:

• —Query token values in build scripts without maintaining a separate config file.
• —Validate component usage in CI: check that the tokens a component references still exist in the system.
• —Feed design context into AI-assisted workflows without copying and pasting token tables.
• —Audit the design system at scale: ask an AI to find all components using a specific semantic token and report what would change if you rename it.

Every project generates a DESIGN.md file that describes the entire design system in a single document: resolved token values per theme, typography specifications, spacing scale, and component anatomy. It is always current because it is regenerated on every change.

Use it to:

• —Hand it to an AI at the start of a conversation so it immediately understands your system without any additional prompting.
• —Include it in a developer onboarding document so new team members understand the token vocabulary from day one.
• —Attach it to a design brief to give context about the existing system before proposing changes.

Unlike a manually written design brief, DESIGN.md is never out of date. It is not a quarterly snapshot; it reflects today's system.

The MCP server exposes a get_design_doc tool that returns the full DESIGN.md content over MCP. Any MCP client can call it to fetch the current state of your design system.

It is the quickest way to hand an AI the whole picture, but it is one of many tools. Read tools let a client explore the system; read-write tools let it make changes, each recorded as an undoable change set. A read-only token only ever sees the read tools. See the full tool reference below.

A read_write token can also update the editable description section at the top of DESIGN.md. That section is hand-authored prose: what the design system is for, the brand voice, design principles, and anything else an AI should know before working with your tokens. The generated reference sections (resolved token values, typography specs, etc.) are always machine-produced and cannot be overwritten via MCP.

All writes via MCP are audited and undoable. The recent AI activity panel in Settings shows a full log of every MCP change.

Examples of what you can ask an AI to do. Read-only prompts work with any token; edit prompts require a Read + Write token.

How do I switch themes in the generated package? Link me to the docs.

Generate a Card component using our design system tokens for background,
border, padding, and typography. Use the exact token names from the system.

Our primary brand color has changed from #2563EB to #7C3AED.
Update the foundation token and check if any semantic tokens need adjusting.

Make the brand container background a softer lilac in light mode
and a deeper purple in dark mode.

Create a dark theme. Base it on Light but invert the background and
surface colors. Keep text and status colors unchanged.

Go to Project Settings and open the MCP / AI tab. Generate a token, choose a scope (Read only or Read + Write), and copy the server URL and token into your MCP client's config file.

Example client configuration:

{
  "mcpServers": {
    "zaklad": {
      "url": "https://platform.zaklad.app/api/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Tokens are scoped to a single project. A read-only token is safe to share with tools that only need to query the system. A read-write token should be treated like an API key; keep it out of version control.

Beyond reading and editing, a connected AI can evaluate the quality of your design system against a curated rubric. Ask things like "is my colour palette any good?", "are my token names sensible?", "is my semantic layer bloated?", or "what icon set should I use?".

Four read-only tools supply the grounding. list_principles and search_principles find the relevant rubric; get_principle returns a principle in full (the principle, why it matters, how to check it, and anti-patterns) plus its authority tier and real sources, so the AI can tell an industry law from a house preference and cite a source when you ask it to prove a claim. get_reference_design_system returns the real, current shape of the reference design system as a worked example to compare against.

The advice reaches beyond this platform into general best practice and the wider tooling landscape, and it is steerable by design: the rubric is curated and version-controlled, contested positions carry both sides, and the factual half is computed live so it never goes stale. The AI does the reasoning; these tools give it something solid to reason over.