Design system MCP server vs CLI: choose the right delivery route

An MCP server and a CLI are interfaces. An agent's choice of interface doesn't make either one the design-system authority. That authority is the approved source of the decisions. A versioned artifact carries some of those decisions, and the interface retrieves or applies it. The consuming project then maps the artifact into files, frameworks, components, and rendered screens.

Keep six layers separate: the design-kit authority, the source version, the emitted artifact, the access interface, the consuming project's mapping, and the observed UI. This matters because two routes can both succeed while resolving different source versions. The reverse is also possible: two files can differ in serialization while expressing the same required token roles and rules.

Don't divide the choice into MCP for production and CLI for development. That misses the actual design-system job. A team may use MCP for catalog discovery, a CLI for an explicit repository write, and either route for inspection. The recommendation changes with credential ownership, service availability, the local environment, schema stability, and the evidence you need to retain.

These defaults are conditional, not rankings. CLI execution often exposes the local machine's filesystem, environment, and installed credentials. This can make a developer workflow convenient, but it also makes the local permission boundary part of the design. MCP can provide a structured interface and a clearer service boundary, but using the protocol doesn't solve authentication by itself. The server, client, and deployment still determine who is represented, which credentials are used, and what is logged.

Service lifecycle also affects the decision. An MCP route may be healthy, unavailable, connected to the wrong environment, or exposing a newer schema than the client expects. A CLI may be absent, outdated, resolved from an unexpected path, or running under a shell with different credentials. Record these conditions instead of reducing them to a single success flag.

Route parity is not byte equality. A DTCG file, CSS variables, Tailwind configuration, and DESIGN.md can serialize different information for different consumers. The testable claim is narrower: within the comparison scope, both routes resolve the same authority and source version, identify their outputs, and preserve the required semantic meaning.

Copy the record below before running either route. The example uses Ambient Sage and a fictional Next.js consumer, but every observation remains explicitly unexecuted. Unknown versions stay unknown. Filling a placeholder with a guess would make the record look complete while destroying its value.

route_parity_record:
  status: unexecuted
  scope: one Ambient Sage semantic color artifact for one named consumer

  authority:
    owner: Identity Forge
    kit: ambient-sage
    source_version: unknown
    source_version_state: unresolved

  mcp_route:
    interface_version: unknown
    artifact_identity: unknown
    format: unknown
    retrieval_state: unexecuted
    retrieved_source_version: unexecuted
    authentication_owner: project developer
    authentication_boundary: MCP client and configured Identity Forge service

  cli_route:
    cli_version: unknown
    artifact_identity: unknown
    format: unknown
    retrieval_state: unexecuted
    retrieved_source_version: unexecuted
    authentication_owner: project developer
    authentication_boundary: local process, environment, and filesystem permissions

  expected_semantic_equivalence:
    claim: Both routes resolve the same recorded authority and source version and preserve the in-scope semantic role names, mode assignments, and values required by the consumer.
    byte_identity_required: false

  comparison_method:
    - Resolve and record the source version returned by each route.
    - Inventory the in-scope semantic roles in each retrieved artifact.
    - Normalize only documented format differences.
    - Compare role presence, mode, value, alias target, and stated usage rule.
    - Record every mismatch without selecting a winner from route preference.

  comparison_results:
    authority_match: unexecuted
    source_version_match: unexecuted
    required_role_coverage: unexecuted
    semantic_value_match: unexecuted
    usage_rule_match: unexecuted

  named_consumer: storefront-nextjs

  fallback_conditions:
    permitted_only_if: The fallback resolves the same recorded authority and source version and supplies every required in-scope field.
    otherwise: Stop and report the mismatch or missing evidence.

  stale_result_rule: Reject a cached or local result when its source version is older than, different from, or unresolvable against the accepted source version.
  unsupported_operation_rule: Stop and report the unsupported operation. Do not imitate it with an unrecorded route or inferred data.
  silent_substitution: prohibited
  verification_status: unexecuted

Set a hybrid precedence rule before either route fails. Without one, the agent may treat availability as authority and silently accept whichever output is easiest to reach. Use the accepted source record as the gate. The interface may change; the authority and accepted source version may not.

1. 1

   Resolve the preferred route

   Attempt the route selected for this task. Record its interface version, identity boundary, retrieval state, artifact identity, format, authority, and returned source version.

2. 2

   Reject stale, incompatible, or incomplete results

   A result is unusable when its source version differs from the accepted version, cannot be resolved, omits a required field, or uses a schema the consumer cannot interpret. Availability does not override these failures.

3. 3

   Evaluate the fallback against the same source record

   The fallback may proceed only if it resolves the same authority and accepted source version and supplies every field required by the task. A local file with unknown age is not a valid fallback.

4. 4

   Stop on unsupported behavior

   If neither route supports the operation under the recorded permissions and versions, report the unsupported operation. Do not invent output, copy from an unverified cache, or claim that a partial result is complete.

5. 5

   Retain evidence from the chosen route

   Record which route supplied the accepted artifact and why. Keep the rejected route's failure state so a later investigation can distinguish service, schema, invocation, and source-version problems.

If an MCP service is unavailable, a CLI fallback is valid only after the CLI result identifies the same authority and source version. The same rule applies to an MCP result replacing a stale CLI artifact. When one route returns an incompatible format, transformation is a separate operation with its own identity and result. Combining fields from incomplete routes requires an explicit merge contract. It isn't parity and shouldn't happen silently.

Governance should fit the operating context. A developer working alone may own the executable, credentials, and repository. A shared service may need separate owners for access policy, schema changes, uptime, and audit records. Record those owners where they affect the route. This article doesn't prescribe an enterprise identity architecture, but the identity boundary must be visible before anyone trusts the route's results.

Ambient Sage is useful here because its kit page is public and the Identity Forge guides document both MCP and direct delivery paths. The kit has a warm-sage visual direction, Plus Jakarta Sans for its primary typography, JetBrains Mono for code-like roles, and a semantic system intended to travel beyond a color-and-font pair. This gives a parity exercise real fields to inspect.

Identity Forge documents MCP tools that can search kits, retrieve design guidance and tokens, and apply a kit. It also documents the direct CLI form identityforge apply ambient-sage, plus a shadcn registry route. The frozen first-party guides verify those capabilities and syntax. They don't prove that a particular MCP session and CLI installation use compatible versions, that both returned the same artifact revision, or that a consuming application adopted the result.

A bounded test could select one semantic color role and its light and dark assignments, retrieve the relevant artifact through each route, and compare that decision after normalizing documented format differences. The record should remain unverified until both retrievals run. Even a passing route comparison would approve only the stated artifact scope, not every export, component, or application screen.

Parity ends at the delivered artifact. Product acceptance begins there. A route can return the right tokens while the project imports an older file, maps a semantic role to the wrong variable, uses a detached component, or overrides the result locally. A separate named-consumer record keeps retrieval success from being mistaken for a successful implementation.

The fictional record below traces the primary action color into storefront-nextjs. It defines useful inspection criteria and failure conditions, but it doesn't pretend that any command, build, browser inspection, or visual review occurred.

consumer_acceptance_record:
  status: unexecuted
  consumer: storefront-nextjs
  artifact_scope: ambient-sage primary action color in light mode
  accepted_authority: Identity Forge / ambient-sage
  accepted_source_version: unknown
  accepted_route: unresolved

  discovery:
    expected: The selected route identifies ambient-sage from the accepted authority.
    observed: unexecuted
    failure_condition: Kit identity or authority is missing, ambiguous, or different.

  retrieval:
    expected: The route returns the recorded source version and identifies the retrieved artifact and format.
    observed: unexecuted
    failure_condition: Retrieval fails, returns an unresolvable version, or omits the required artifact identity.

  artifact_validation:
    expected: The artifact contains the required primary role and its light-mode value or documented alias target.
    observed: unexecuted
    inspection: Inspect the retrieved artifact, not a search result or generated summary.
    failure_condition: The role is missing, malformed, unresolved, or differs from the accepted source decision.

  project_mapping:
    expected: storefront-nextjs imports the accepted artifact and maps the primary role to the project's shared primary variable or theme role.
    observed: unexecuted
    inspection: Record the importing file, transformation step, resolved version, and destination role.
    failure_condition: The project loads another version, duplicates the value locally, or maps the role to a different destination.

  component_adoption:
    expected: The named primary button uses the shared project role in its default state without an unrecorded override.
    observed: unexecuted
    inspection: Inspect the component definition, variant, state rule, and any wrapper or local class.
    failure_condition: The component uses a literal color, another token, a detached copy, or an undocumented exception.

  observed_rendering:
    expected: In the recorded light-mode fixture, the named button resolves to the accepted primary role under the recorded state and environment.
    observed: unexecuted
    inspection: Record fixture, mode, viewport, state, computed value, and visible result.
    failure_condition: The computed or visible result differs, cannot be observed, or lacks enough context to compare.

  first_divergent_layer: unexecuted
  disposition: unexecuted
  allowed_dispositions:
    - accept
    - revise
    - block
  acceptance_rule: Accept only when every required stage has supporting evidence and no unresolved divergence remains.

When the final UI differs from the expectation, start at the authority and move downstream. Correct the first divergent layer first. Later mismatches may be consequences rather than independent causes.

1. 1

   Check source authority

   Confirm the expected decision, kit identity, and accepted source version. If those are unresolved, later comparisons have no stable reference.

2. 2

   Check the MCP service or schema

   For an MCP retrieval, inspect service availability, represented identity, authentication scope, tool or resource schema, returned artifact identity, and source version.

3. 3

   Check the CLI invocation and environment

   For a CLI retrieval, inspect the executable version, arguments, working context, credentials, exit state, output, written targets, and returned artifact identity.

4. 4

   Check transformation and artifact output

   Inspect any conversion between DTCG, CSS, Tailwind, DESIGN.md, registry data, or another format. Confirm required roles survived and references resolved as intended.

5. 5

   Check project mapping

   Confirm the named project loads the accepted artifact version and maps the intended source role to the intended local role.

6. 6

   Check component adoption

   Confirm the named component, variant, and state consume the mapped role without an unrecorded local override or detached implementation.

7. 7

   Check the rendered consumer

   Inspect the recorded environment and compare the computed and visible result with the expectation. Do not infer a browser result from artifact validity alone.

This order also makes failures easier to observe. A service log may explain an MCP authentication failure, while terminal output may explain a CLI invocation problem. An artifact diff can reveal transformation drift. Project inspection may expose a stale import, and component inspection may reveal a literal value. The useful record connects these observations instead of blaming the interface named in the original request.

Identity Forge can supply complete design kits through MCP, CLI, registry, and artifact exports. The consuming team still owns credential policy, route configuration, version recording, repository permissions, transformations, framework integration, component behavior, exceptions, runtime inspection, and release acceptance.

A kit can define semantic color roles, typography, spacing, layout guidance, motifs, and written rules. It can't prove that an agent used the intended route, that two installed interfaces resolved the same version, that a project imported the expected files, or that a rendered interface satisfies product and accessibility requirements. Those claims need evidence from the environment where they occur.

Choose one artifact and one named consumer. Complete the route-parity record first, then the consumer-acceptance record. Retain both MCP and CLI only if they resolve the same recorded authority and source version, preserve the required semantics, and lead to acceptable downstream evidence. If either route can't meet that bar, keep the route that does and record why the other remains unavailable, stale, incompatible, incomplete, or unsupported.

• MCP vs. CLI for AI-native development: CircleCI presents CLI as a strong fit for local inner-loop work and MCP as structured access for outer-loop workflows, while stating that neither interface is universally better.
• MCP vs. CLI: When to Use Them and Why: Descope argues that the choice depends on who the agent represents and how identity and authentication must work as deployment scope widens.
• CLI vs MCP: You're Asking the Wrong Question: Lunar distinguishes developer-local tooling from shared organizational access and raises concerns about governance, observability, credentials, and server failures.
• MCP Servers vs CLI Tools for AI Agents: When to Use Each: MindStudio describes CLI calls as subprocess operations with inspectable output and notes that MCP servers introduce setup and process-lifecycle responsibilities.
• MCP vs CLI: Decision guide: This agent-specific guide includes the end user, model, observability needs, and frequency of schema changes among the relevant interface-selection questions.
• Design systems for AI coding agents: Identity Forge documents MCP, CLI, and shadcn registry delivery for its design kits, including a direct CLI application path for the free Ambient Sage kit.
• Give Claude Code a design system: Identity Forge documents MCP tools for kit search, design guidance, token retrieval, and application, alongside direct CLI and registry paths for Claude Code projects.
• Ambient Sage Design Kit: The public Ambient Sage page documents a free design kit with a warm-sage visual system, Plus Jakarta Sans typography, JetBrains Mono, semantic design decisions, and installation guidance.