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