Strata MCP — @strata-ds/mcp

@strata-ds/mcp is the official MCP server for Strata — the design-token and component platform. It exposes your published design system (tokens, components, insights, baseline presets) to any MCP-capable agent host: Claude Desktop, Cursor, ChatGPT connectors, and hosted copilots.

Full specs: docs/specs/tool-surface.md

Quick start

{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-ds/mcp"],
      "env": {
        "STRATA_SYNC_TOKEN": "pt_live_..."
      }
    }
  }
}

STRATA_SYNC_TOKEN is optional — omit it to browse any public Strata project. Set it to access private projects and unlock sync tools.

Three hosts, three purposes

Strata uses three distinct hosts. This server treats them separately:

| Host | Env var | Purpose | Used by | |---|---|---|---| | https://api-production-charisol-design-system-be.aws.charisol.io | STRATA_API_BASE_URL | REST API — project metadata, sync reads, insights, baseline presets | All MCP tools | | https://cdn.strata.charisol.io | (none — not used by this server) | Web-component JS bundle (<strata-dynamic>) for browser users only | Not used here | | snapshotCdnBase (per-project, from API response) | (none — never hardcoded) | Edge-cached snapshot files: variables.css, tokens.ts, strata.json, etc. | get_tokens, list_asset_formats |

The snapshot CDN base is returned by the API on each project record. This server reads it from there — it never constructs or hardcodes CDN URLs.

Tools

Public (no token required)

| Tool | Backing endpoint | Description | |---|---|---| | list_projects | GET /v1/public/projects | List public projects with pagination | | get_project | GET /v1/public/projects/:id | Full project record including inline variables, components, and snapshotUrls | | list_asset_formats | GET /v1/public/projects/:id/assets | List all downloadable token format files with CDN URLs | | get_tokens | reads snapshotUrls → CDN fetch | Fetch raw content of any token format (CSS, TS, JSON, Swift, Dart…) |

Sync (always require STRATA_SYNC_TOKEN)

Note: /v1/sync/* endpoints require a sync token even for projects that appear in the public listing. Generate one in the Strata dashboard → Publish & Sync tab. Token format: pt_live_<random>.

| Tool | Backing endpoint | Description | |---|---|---| | list_variables | GET /v1/sync/:id/variables | Design token variables (name, value, type, CSS key, layer) | | list_components | GET /v1/sync/:id/components | Component definitions with props and node trees referencing token vars | | get_component | filters list_components | Single component by name (case-insensitive) |

Compute (require STRATA_SYNC_TOKEN except get_baseline_preset)

| Tool | Backing endpoint | Auth | Description | |---|---|---|---| | get_insights | GET /v1/sync/:id/insights | Token required | Aggregate drift counts: explicitlySetCount, atDefaultCount, customTokenCount | | suggest_tokens | delegates to get_insights | Token required | Returns insight counts + note directing to dashboard for full AI recommendations | | get_baseline_preset | GET /v1/baseline/preset | None | Full 3-layer baseline token preset (151 vars, 23 components); optional brandPrimary hex override |

Example get_baseline_preset output:

{
  "meta": { "variableCount": 151, "componentCount": 23,
            "layers": { "foundation": 72, "semantic": 39, "component": 40 } },
  "catalog": {
    "tokens": {
      "foundation": [{ "key": "--color-brand-primary-300", "name": "Brand Primary 300", "type": "color" }, "..."]
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | STRATA_API_BASE_URL | No | https://api-production-charisol-design-system-be.aws.charisol.io | Strata REST API base URL | | STRATA_SYNC_TOKEN | No | — | Project sync token (pt_live_...) for private projects | | STRATA_BASE_URL | No | — | Deprecated — renamed to STRATA_API_BASE_URL. Emits a warning at startup. Removed in v0.1.0. |

MCP client config examples

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-ds/mcp"],
      "env": {
        "STRATA_SYNC_TOKEN": "pt_live_your_token_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "strata": {
      "command": "npx",
      "args": ["-y", "@strata-ds/mcp"],
      "env": {
        "STRATA_SYNC_TOKEN": "pt_live_your_token_here"
      }
    }
  }
}

Omit STRATA_SYNC_TOKEN entirely for public projects.

Requirements

• Node.js ≥ 18

Development

npm install
npm run build   # tsc → dist/
npm start       # start stdio server
npm run dev     # tsx (no build step)
npm run typecheck

How to release

Releases are automated via .github/workflows/publish.yml. The workflow triggers on any v* tag.

# 1. Bump the version in package.json
npm version patch          # or minor / major / 0.0.2-alpha.0 etc.

# 2. Push the commit and the tag
git push --follow-tags

# CI will: install → build → npm publish --dry-run → npm publish --access public

Verify a publish succeeded:

npm view @strata-ds/mcp

The NPM_TOKEN secret must be set in repo Settings → Secrets and variables → Actions before the first publish.