Stoaken for AI assistants and agents

Why Stoaken

Stoaken keeps a design system’s tokens (W3C design tokens, DTCG 2025.10) and its components in one place, and sends every change through review: a release only goes live when a person approves it. Agents, scripts and CI read the live release and propose changes through the same review, with the same roles as the person whose key or sign-in they use.

• One source of truth: Brands hold token sets; a theme stacks sets and can have modes (light and dark, density). Exports, the CLI, the API and agents all read the same published release.
• Reviewed, not silent: an agent’s change becomes a release that waits in the Command Center for a person. Reviewers see what changed, what it reaches, and pictures of components in each mode.
• Three ways in for agents: the MCP server (for AI tools), the REST API (for scripts) and the stoaken CLI (for projects and CI).

Before you start (a person does this)

1. Sign up at stoaken.com and create a Brand (Overview › Create a Brand). There is no API or MCP tool that creates a Brand or a new token set; an agent works inside Brands a person made.
2. Bring the first tokens in (see Get tokens in), or choose Sample tokens to try things out.
3. For scripts, CI and API-key sign-in: create a key on Settings › Developer access (/settings/developer). A key acts as you, with your role on each Brand; revoke it there at any time. Never put a key in a public web page or commit it.

• Viewer
  What an agent using your access can do

  Read tokens, releases and changes; export files.
• Reviewer
  What an agent using your access can do

  The same as a Viewer through the API and agents (approving is done by a person in the app).
• Editor
  What an agent using your access can do

  Also propose token changes and deprecations, add or change themes, and import components.
• Admin
  What an agent using your access can do

  Also manage webhooks (Brand Admin) and members and invitations (workspace Admin).

Connect an AI tool to the MCP server

The MCP server is at https://www.stoaken.com/mcp (Streamable HTTP). It accepts an API key as Authorization: Bearer <key>, or a browser sign-in (OAuth).

1. In your project, run npx stoaken init. It signs you in (browser, or paste an API key), lets you pick a Brand, sets up your AI tool and writes stoaken.config.json (commit it), .stoaken/credentials.json (git-ignored) and .stoaken/SKILL.md, a guide to the tools your AI tool can read.
2. Pick the tool when asked, or name it: npx stoaken init --client claude-code. The names it takes: claude-code, claude-desktop, cursor, codex, copilot, v0, windsurf, zed, gemini-cli, jetbrains, cline, lovable, bolt, replit.
3. Check the setup any time with npx stoaken status (CLI 0.6.0 or later). It changes nothing and exits 1 when a check fails.

To add the server by hand in Claude Code with an API key:

claude mcp add --transport http stoaken https://www.stoaken.com/mcp --header "Authorization: Bearer $STOAKEN_API_KEY"

Signing in instead of a key. Add the server with just its URL and start your tool’s sign-in (in Claude Code, /mcp). A request without credentials gets 401 with a WWW-Authenticate header naming https://www.stoaken.com/.well-known/oauth-protected-resource (RFC 9728), which names the sign-in service. Your browser opens Stoaken’s sign-in, then a consent screen naming the tool. Tools that publish a Client ID Metadata Document are recognised by its URL; others register first (Dynamic Client Registration). Company sign-in (SSO) works the same way.

stoaken init never writes your API key into the AI tool’s config: with a key, the config names the STOAKEN_API_KEY environment variable instead.

What the MCP tools do

There are 26 tools: 13 that only read and 13 that change something. Start with get_started or list_brands, then get_brand for the ids every other tool takes.

• get_started
  What it does

  Where to begin: your Brands, your role on each, and what you can do there.
  Changes things?

  No
• list_brands
  What it does

  The Brands you can see, with your role on each.
  Changes things?

  No
• get_brand
  What it does

  A Brand's themes, token sets and modes: every id the other tools take.
  Changes things?

  No
• get_token_set
  What it does

  One token set as stored, with the hash to edit it safely.
  Changes things?

  No
• get_theme_tokens
  What it does

  A theme's tokens as stored.
  Changes things?

  No
• get_resolved_theme_tokens
  What it does

  Tokens as a release would publish them, for any mode.
  Changes things?

  No
• list_deprecated_tokens
  What it does

  What is deprecated, its replacement, and what still uses it.
  Changes things?

  No
• list_releases
  What it does

  A theme's releases, their status and what changed, counted by kind.
  Changes things?

  No
• release_changes
  What it does

  Every change in a release, mode by mode, against the one before or any other.
  Changes things?

  No
• release_timeline
  What it does

  What happened to a release and when: sent, handed on, approved, rejected.
  Changes things?

  No
• export_tokens
  What it does

  A live release as CSS, SCSS, Tailwind, Swift, Android or JSON, ready to commit.
  Changes things?

  No
• list_webhooks
  What it does

  A Brand's webhooks, their health and latest deliveries.
  Changes things?

  No
• create_webhook
  What it does

  Add a webhook (the secret is returned once).
  Changes things?

  Settings
• update_webhook
  What it does

  Change or re-enable a webhook.
  Changes things?

  Settings
• rotate_webhook_secret
  What it does

  New signing secret; the old one signs for 24 hours.
  Changes things?

  Settings
• ping_webhook
  What it does

  Send a signed test event.
  Changes things?

  Settings
• list_members
  What it does

  Your workspaces, or one workspace's members and open invitations.
  Changes things?

  No
• create_workspace
  What it does

  Add a workspace (say, one per client) next to one you administer.
  Changes things?

  Settings
• invite_members
  What it does

  Invite up to 50 people with the same access; each gets an email.
  Changes things?

  Settings
• revoke_invitation
  What it does

  Withdraw an open invitation.
  Changes things?

  Settings
• create_theme
  What it does

  Create a theme from token sets, optionally copying modes.
  Changes things?

  Settings
• update_theme
  What it does

  Rename a theme or change its sets.
  Changes things?

  Settings
• delete_theme
  What it does

  Delete a theme that was never released.
  Changes things?

  Settings
• propose_token_change
  What it does

  Edit a token set and submit it for review.
  Changes things?

  Proposes a release for review
• propose_token_edits
  What it does

  Set, add, rename or delete tokens (or a whole group) and submit for review.
  Changes things?

  Proposes a release for review
• propose_token_deprecation
  What it does

  Deprecate a token, reviewed like any other change.
  Changes things?

  Proposes a release for review

The server also offers ready-made prompts (in Claude Code, type /mcp__stoaken__get_started). Tools that don’t show prompts can call the get_started tool instead.

• get_started: Lists your Brands and your role on each, sums up their themes, and offers what you can do.
• use_tokens: Reads a theme’s tokens and swaps hard-coded values in the open file for them.
• deprecation_cleanup: Lists deprecated tokens grouped by what replaces them, and offers to fix their uses in the repo.
• sync_tokens_file: Exports a theme’s live release and writes it to a file in the repo.
• propose_edit: Turns a change you describe into token edits and sends them for review.
• whats_changed: Sums up a theme’s latest release: what changed and who did what.

Get tokens in

The first tokens come in through the app, where a person sees what was read before it’s saved. On Overview, Bring your tokens (a new Brand, or Add a token set on one) takes:

• A W3C design tokens file (.json, up to 1 MB), uploaded or pasted. Exports from Tokens Studio, Style Dictionary and Figma variables plugins usually are.
• A Tailwind config: tailwind.config (v3) or an @theme block (v4). Stoaken reads it without running it and keeps what you changed from Tailwind’s defaults.
• From Figma: the Stoaken plugin’s Copy for Stoaken copies a variable collection with every mode; paste it in. See Figma.
• Penpot: connect a file on Settings › Penpot and sync tokens both ways. See Penpot.

After that, an agent or script changes tokens in an existing token set, then proposes a release. Over MCP, propose_token_edits does both in one call (set, add, rename, delete, rename a group, describe). Over REST:

# 1. Read the set and its hash
curl -H "Authorization: Bearer $STOAKEN_API_KEY" https://www.stoaken.com/api/token-sets/$TOKEN_SET_ID

# 2. Edit tokens (all or nothing; refused with 409 if the set changed since base_hash)
curl -X PATCH https://www.stoaken.com/api/token-sets/$TOKEN_SET_ID/tokens \
  -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Idempotency-Key: edit-spacing-lg-1" \
  -H "Content-Type: application/json" \
  -d '{"base_hash":"<document_hash>","operations":[{"op":"set","path":"spacing.lg","value":{"value":24,"unit":"px"}}]}'

# 3. Propose a release of the theme (sent for review; never published)
curl -X POST https://www.stoaken.com/api/themes/$THEME_ID/releases \
  -H "Authorization: Bearer $STOAKEN_API_KEY" \
  -H "Idempotency-Key: release-1-4-0" \
  -H "Content-Type: application/json" \
  -d '{"version":"1.4.0","version_type":"minor"}'

To replace a whole set, PUT /api/token-sets/{tokenSetId}/document takes a full DTCG document. Saving never publishes anything: only a release does, once a person approves it. Every write needs an Idempotency-Key header.

Bring components in

Every way in ends in the same Review in Stoaken, where a person answers any questions and presses Import. Stoaken never reads your repository or your Figma files: you send what you choose.

• Your code (CLI or CI)
  How

  npx stoaken components push works the plan out on your machine and sends it for review.
  Status

  Needs CLI 0.7+, which isn’t on npm yet (npm has 0.6.0).
• A folder in the browser
  How

  Drop a components folder on Components › Import; the plan is worked out in your browser.
  Status

  Live.
• Figma
  How

  The Stoaken plugin 1.4, Components tab: select component sets, components or instances, then Send selection. Download it from Figma.
  Status

  Live.
• Penpot
  How

  Penpot components can’t be imported yet. Penpot tokens sync today.
  Status

  Not built yet.

# A dry run: the plan in your terminal. Sends nothing, needs no key, free on every plan.
npx stoaken components push ./src/components --check

# Send it to your Brand's Review
npx stoaken components push ./src/components --brand <brand id>

# In CI: import only what needs no decision; the rest waits for a person
npx stoaken components push ./src/components --yes

It reads React and Preact components (.tsx, .ts, .jsx, .js), their relative imports, tsconfig paths and workspace packages. Vue and Svelte files are listed but not imported yet. Importing is part of the Team plan (the 14-day trial includes it); --check is free. The key’s person needs Editor on the Brand.

The CLI uses these REST endpoints, which a script can call directly: POST /api/brands/{brandId}/component-modules/missing, PUT /api/brands/{brandId}/component-modules, POST /api/brands/{brandId}/component-imports, GET /api/component-imports/{importId} and POST /api/component-imports/{importId}/apply. Their shapes are in the OpenAPI document.

Read tokens to write code

• MCP: get_resolved_theme_tokens returns tokens as a release would publish them, for any mode; narrow it with path (e.g. color.brand) and mode. export_tokens writes the live release as a file. list_deprecated_tokens says what to stop using and what replaces it.
• CLI: npx stoaken export --format css --out src/tokens.css. With no options it runs every target saved in stoaken.config.json; --check fails CI when the committed file is behind the live release.
• REST: GET /api/themes/{themeId}/tokens?mode=<key> (resolved) and GET /api/themes/{themeId}/export?format=<format> (a file).

Formats: css, css-auto, json-dtcg, json-sd4, js, ts, scss, tailwind, tailwind4, swift, compose, android. See Export formats. Exports carry no timestamps, so a re-export with no token changes produces no diff.

Propose a release

1. Find the theme with get_brand (MCP) or GET /api/brands/{brandId}/themes (REST), and the next free version with list_releases.
2. Propose: propose_token_edits for targeted changes, propose_token_change to replace a whole set, propose_token_deprecation to deprecate a token. Over REST, edit the set then POST /api/themes/{themeId}/releases.
3. Tell the person where to review it: the result links to the Command Center. Track it with release_timeline; see every change with release_changes.
4. Once a person approves it, it’s live: exports, the CLI, the API and agents read the new values, and signed webhooks tell your pipeline.

Use major for breaking changes (removed or renamed tokens), minor for additions and patch for value fixes. Breaking changes need an Admin to approve.

Prompts to give your assistant

Copy one of these into Claude Code, Cursor or another AI tool once it’s connected:

Connect this repo to Stoaken: run `npx stoaken init`, then call get_started and tell me my Brands, my role on each and what I can do.

Read the Default theme’s resolved tokens from Stoaken (default and dark mode), then replace hard-coded colours and spacing in src/components/Card.tsx with the matching tokens from our export.

Export our live Stoaken release as Tailwind 4 with export_tokens and update src/theme.css. Show me the diff before writing.

Propose raising spacing.lg to 24px in Stoaken as a minor release with propose_token_edits. If it’s refused, tell me the fix it gives instead of retrying.

Run `npx stoaken components push ./src/components --check` (CLI 0.7+) and summarise what would come into Stoaken and what needs a decision. Don’t send anything.

Which Stoaken tokens are deprecated in the Default theme, what replaces them, and where does this repo still use them?

Limits and plain errors

• REST and MCP: 120 requests a minute per key or sign-in (one bucket for both). REST writes: 60 an hour. MCP changes: 30 an hour.
• Plans: on Free, the API, CLI and agents are read only (reading and export still work); proposing changes, importing components and webhooks are Team. During early access every account has the Team features; limits apply once billing starts. See Pricing.
• Sizes: a component push sends a plan of up to 2 MB; a Figma send reads up to 5,000 layers and 4 MB; a token file upload is up to 1 MB.

• 401 unauthorized
  What it means

  No key or sign-in, or a revoked key.
  What to do

  Make a key on Settings › Developer access, or sign in again (npx stoaken init, or /mcp in Claude Code).
• 403 with code: plan_limit
  What it means

  The Brand is on the Free plan.
  What to do

  Upgrade to Team on Organization › Billing (the trial includes it). Reading, export and components push --check stay free.
• 403 with code: not_allowed, or a role refusal
  What it means

  Your role on the Brand doesn’t allow it.
  What to do

  Tokens and themes need Editor, webhooks need Admin. Ask a Brand Admin.
• 400 idempotency-key-required
  What it means

  A write without an Idempotency-Key header.
  What to do

  Send a unique key per change; repeat the same key to retry safely.
• 409 conflict (token edits)
  What it means

  The set changed since you read base_hash.
  What to do

  Read the set again, re-apply your edits, send the new hash.
• 409 with code: duplicate_ident
  What it means

  A component name clashes with one the Brand has.
  What to do

  Decide the clash in the Review link, or rename it in code.
• 413 with code: too_large
  What it means

  Too much in one push.
  What to do

  Send a folder at a time, or smaller batches.
• 429 rate-limited
  What it means

  Over the rate limit.
  What to do

  Wait for Retry-After, or batch edits into one propose_token_edits call.

Errors are RFC 9457 problem documents with a plain detail (and often fix). A refused change says what to fix, so retrying the same call won’t help. More in MCP troubleshooting and the REST API.

Safety

• Sealed previews: imported components are drawn on stoakenbox.com, a separate site with no sign-in, no cookies and no secrets, in a sandboxed frame whose content policy refuses every network request. Previews only open inside stoaken.com.
• Your access, no more: every call runs as the person whose key or sign-in it uses, inside their role on each Brand, enforced in the database.
• Keys stay out of web pages: the API reads keys only from the Authorization header, never a cookie.

What Stoaken won’t do

• Let an agent, API key or CLI approve or publish a release. There is no tool or endpoint for it: agents propose, people approve.
• Read your repository or your Figma files. The CLI and the plugin send only what you choose.
• Decide for you. components push --yes imports only components with no open question; the rest wait for a person in the Review.
• Create Brands or token sets through the API or MCP. A person does that in the app.

Machine-readable

• /llms.txt: a short index of these pages for AI tools; /llms-full.txt: the same with this whole guide.
• /api/openapi.json: the REST API as OpenAPI 3.1.
• https://www.stoaken.com/.well-known/oauth-protected-resource: OAuth protected resource metadata for the MCP server.
• https://www.stoaken.com/mcp: the MCP server.