# Stoaken

> Stoaken is a design system workspace: design tokens (W3C DTCG) and components in one place, and every change reviewed by a person before it reaches code. AI agents connect over MCP, scripts over the REST API, projects and CI with the `stoaken` CLI. Agents read and propose; people approve.

Use the MCP server (https://www.stoaken.com/mcp) to read tokens and propose changes from an AI tool, the CLI to export tokens into a project and push components, and the REST API (https://www.stoaken.com/api/openapi.json) for scripts. A person creates the account and Brand first.

## Start here

- [Stoaken for AI assistants and agents](https://www.stoaken.com/docs/ai): how, why and where to get a design system onto Stoaken with MCP, the CLI and the REST API, step by step.
- [Quickstart](https://www.stoaken.com/docs/quickstart): from sign-up to a reviewed release and an exported token file.
- [Concepts](https://www.stoaken.com/docs/concepts): workspaces and roles, Brands, token sets, themes, modes, releases and review.
- [Developers](https://www.stoaken.com/developers): the REST API, MCP server, webhooks and CLI on one page.

## Connect an agent (MCP)

- [AI agents (MCP)](https://www.stoaken.com/docs/mcp): connect Claude Code and other MCP clients; 26 tools, example prompts, troubleshooting.
- MCP server: https://www.stoaken.com/mcp (Streamable HTTP). Auth: `Authorization: Bearer <API key>` from Settings › Developer access, or OAuth sign-in discovered at https://www.stoaken.com/.well-known/oauth-protected-resource.
- Quickest setup: `npx stoaken init` in the project (signs in, picks a Brand, configures the AI tool, writes .stoaken/SKILL.md). Clients: claude-code, claude-desktop, cursor, codex, copilot, v0, windsurf, zed, gemini-cli, jetbrains, cline, lovable, bolt, replit.

## CLI

- [CLI docs](https://www.stoaken.com/docs/cli): `stoaken init`, `stoaken export` (and `--check` in CI), `stoaken status`, `stoaken components push`.
- npm package `stoaken` (run with npx). `components push` needs CLI 0.7+, which is not on npm yet (npm has 0.6.0); the other commands work from 0.6.0.

## REST API

- [REST API docs](https://www.stoaken.com/docs/api): API keys, versions (`Stoaken-Version`), 120 requests a minute, 60 writes an hour, required `Idempotency-Key` on writes, RFC 9457 errors.
- [OpenAPI 3.1](https://www.stoaken.com/api/openapi.json): every endpoint and schema.
- [Webhooks](https://www.stoaken.com/docs/webhooks): signed events when releases are submitted, published or rejected.

## Get a design system in

- [Tokens: JSON, Tailwind, Figma, Penpot](https://www.stoaken.com/docs/ai#tokens-in): W3C design tokens JSON (Tokens Studio, Style Dictionary), a Tailwind v3 config or v4 @theme, Figma variables via the plugin, Penpot sync; then edits over MCP or REST.
- [Components: code, CI, Figma](https://www.stoaken.com/docs/ai#components-in): `stoaken components push` (CLI 0.7+; `--check` free), a folder dropped in the browser, the Figma plugin 1.4 Components tab. Penpot components are not built yet.
- [Figma plugin](https://www.stoaken.com/docs/figma): download (1.4), releases into Figma variables, changes and components back for review.
- [Penpot](https://www.stoaken.com/docs/penpot): sync tokens with a Penpot file, both ways.
- [Export formats](https://www.stoaken.com/docs/exports): 12 formats: css, css-auto, json-dtcg, json-sd4, js, ts, scss, tailwind, tailwind4, swift, compose, android.

## Plans and limits

- [Pricing](https://www.stoaken.com/pricing): Free (one editor; API, CLI and agents read only) and Team (propose changes, import components, webhooks). Everything is free during early access.
- [Limits and errors](https://www.stoaken.com/docs/ai#limits): rate limits, MCP changes (30 an hour), plan_limit and other refusals with what to do.

## Safety

- [Sealed component previews](https://www.stoaken.com/product/components): previews run on stoakenbox.com: a separate site with no sign-in, cookies or secrets, in a sandboxed frame with no network.
- [Safety](https://www.stoaken.com/docs/ai#safety): every call runs as a person, inside their role, enforced in the database.

## What Stoaken won’t do

- [Agents propose; people approve](https://www.stoaken.com/docs/ai#wont): no tool, endpoint or key can approve or publish a release; Stoaken never reads your repository or Figma files; it never decides an import for you.

## Optional

- [Full guide as text](https://www.stoaken.com/llms-full.txt): this file plus the whole AI guide.
- [Components](https://www.stoaken.com/product/components): bring components in and check every release.
- [Help centre](https://www.stoaken.com/help): how each screen of the app works.

---

# Stoaken for AI assistants and agents

> How an AI assistant, coding tool or agent gets a design system onto Stoaken and works with it: connect the MCP server, push tokens, bring components in, read tokens for code and propose releases a person approves.

Source: https://www.stoaken.com/docs/ai (facts checked against the code on 2026-11-03).

## 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](https://www.stoaken.com/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](https://www.stoaken.com/auth/sign-in) 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](https://www.stoaken.com/docs/ai#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](https://www.stoaken.com/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.

| Role on the Brand | What an agent using your access can do |
| --- | --- |
| Viewer | Read tokens, releases and changes; export files. |
| Reviewer | The same as a Viewer through the API and agents (approving is done by a person in the app). |
| Editor | Also propose token changes and deprecations, add or change themes, and import components. |
| Admin | 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:

Terminal:

```
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.

> Signing in from AI tools has to be switched on first. If it isn’t available yet, use an API key from Settings › Developer access.

`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.

| Tool | What it does | Changes things? |
| --- | --- | --- |
| `get_started` | Where to begin: your Brands, your role on each, and what you can do there. | No |
| `list_brands` | The Brands you can see, with your role on each. | No |
| `get_brand` | A Brand's themes, token sets and modes: every id the other tools take. | No |
| `get_token_set` | One token set as stored, with the hash to edit it safely. | No |
| `get_theme_tokens` | A theme's tokens as stored. | No |
| `get_resolved_theme_tokens` | Tokens as a release would publish them, for any mode. | No |
| `list_deprecated_tokens` | What is deprecated, its replacement, and what still uses it. | No |
| `list_releases` | A theme's releases, their status and what changed, counted by kind. | No |
| `release_changes` | Every change in a release, mode by mode, against the one before or any other. | No |
| `release_timeline` | What happened to a release and when: sent, handed on, approved, rejected. | No |
| `export_tokens` | A live release as CSS, SCSS, Tailwind, Swift, Android or JSON, ready to commit. | No |
| `list_webhooks` | A Brand's webhooks, their health and latest deliveries. | No |
| `create_webhook` | Add a webhook (the secret is returned once). | Settings |
| `update_webhook` | Change or re-enable a webhook. | Settings |
| `rotate_webhook_secret` | New signing secret; the old one signs for 24 hours. | Settings |
| `ping_webhook` | Send a signed test event. | Settings |
| `list_members` | Your workspaces, or one workspace's members and open invitations. | No |
| `create_workspace` | Add a workspace (say, one per client) next to one you administer. | Settings |
| `invite_members` | Invite up to 50 people with the same access; each gets an email. | Settings |
| `revoke_invitation` | Withdraw an open invitation. | Settings |
| `create_theme` | Create a theme from token sets, optionally copying modes. | Settings |
| `update_theme` | Rename a theme or change its sets. | Settings |
| `delete_theme` | Delete a theme that was never released. | Settings |
| `propose_token_change` | Edit a token set and submit it for review. | Proposes a release for review |
| `propose_token_edits` | Set, add, rename or delete tokens (or a whole group) and submit for review. | Proposes a release for review |
| `propose_token_deprecation` | Deprecate a token, reviewed like any other change. | Proposes a release for review |

> There is no tool that approves or publishes a release. Proposals wait in the Command Center for a person, exactly as if the change had been made in the app.

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](https://www.stoaken.com/docs/figma#import).
- **Penpot**: connect a file on **Settings › Penpot** and sync tokens both ways. See [Penpot](https://www.stoaken.com/docs/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:

Push tokens 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.

> The CLI doesn’t upload tokens: it connects a project, exports tokens and pushes components. Use MCP or the REST API to change tokens from code.

## 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.

| From | How | Status |
| --- | --- | --- |
| Your code (CLI or CI) | `npx stoaken components push` works the plan out on your machine and sends it for review. | Needs CLI 0.7+, which isn’t on npm yet (npm has 0.6.0). |
| A folder in the browser | Drop a components folder on **Components › Import**; the plan is worked out in your browser. | Live. |
| Figma | The Stoaken plugin 1.4, **Components** tab: select component sets, components or instances, then **Send selection**. Download it from [Figma](https://www.stoaken.com/docs/figma#install). | Live. |
| Penpot | Penpot components can’t be imported yet. Penpot tokens sync today. | Not built yet. |

Terminal (CLI 0.7+):

```
# 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](https://www.stoaken.com/api/openapi.json).

## 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](https://www.stoaken.com/docs/exports). 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](https://www.stoaken.com/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](https://www.stoaken.com/docs/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:

Get 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.
```

Use tokens in code:

```
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.
```

Sync a tokens file:

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

Propose a change:

```
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.
```

Plan a component import:

```
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.
```

Clean up deprecations:

```
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](https://www.stoaken.com/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.

| You see | What it means | What to do |
| --- | --- | --- |
| 401 `unauthorized` | No key or sign-in, or a revoked key. | Make a key on Settings › Developer access, or sign in again (`npx stoaken init`, or `/mcp` in Claude Code). |
| 403 with `code: plan_limit` | The Brand is on the Free plan. | 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 | Your role on the Brand doesn’t allow it. | Tokens and themes need Editor, webhooks need Admin. Ask a Brand Admin. |
| 400 `idempotency-key-required` | A write without an `Idempotency-Key` header. | Send a unique key per change; repeat the same key to retry safely. |
| 409 `conflict` (token edits) | The set changed since you read `base_hash`. | Read the set again, re-apply your edits, send the new hash. |
| 409 with `code: duplicate_ident` | A component name clashes with one the Brand has. | Decide the clash in the Review link, or rename it in code. |
| 413 with `code: too_large` | Too much in one push. | Send a folder at a time, or smaller batches. |
| 429 `rate-limited` | Over the rate limit. | 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](https://www.stoaken.com/docs/mcp#troubleshooting) and the [REST API](https://www.stoaken.com/docs/api#errors).

## 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](https://www.stoaken.com/llms.txt): a short index of these pages for AI tools; [/llms-full.txt](https://www.stoaken.com/llms-full.txt): the same with this whole guide.
- [/api/openapi.json](https://www.stoaken.com/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.