# storykit-mcp

Give an AI structured data and get back a hosted StoryKit widget — or drive the **full Studio** (images, media, brands, canvases, assets, series, workflows) with a personal API key.

1. **Public widgets (no key)** — `find_widgets` → `render_widget` → opaque hosted URL.
2. **Studio tools (`STORYKIT_API_KEY`)** — full owner surface under plan limits (~69 remote tools).

Mint a key + paste-ready LLM prompt: **[asset.storykit.space/ai](https://asset.storykit.space/ai)**

## CRITICAL: which endpoint?

| URL | Auth | Tools |
| --- | --- | --- |
| **`https://asset.storykit.space/api/v1/studio-mcp`** | `Bearer sk_live_…` | Full Studio (images included) |
| `https://asset.storykit.space/api/v1/mcp` | none | **Only** widgets (3 tools) — **no images** |

If `tools/list` lacks `generate_image`, you are on the wrong server.

## Connect

### Remote Studio (HTTP — preferred for images)

```bash
export STORYKIT_API_KEY="sk_live_…"
# Claude / Cursor / any streamable-HTTP MCP client:
# URL:  https://asset.storykit.space/api/v1/studio-mcp
# Header: Authorization: Bearer $STORYKIT_API_KEY
```

```bash
claude mcp add --transport http storykit-studio https://asset.storykit.space/api/v1/studio-mcp \
  --header "Authorization: Bearer ${STORYKIT_API_KEY}"
```

### Remote public widgets only

```bash
claude mcp add --transport http storykit https://asset.storykit.space/api/v1/mcp
```

### Local stdio (widgets always; Studio when key is set)

```bash
export STORYKIT_API_KEY="sk_live_…"   # required for image/studio tools
claude mcp add storykit -- npx -y storykit-mcp@3.3.0
```

Stdio tool names are prefixed with `studio_` (e.g. `studio_generate_image` → remote `generate_image`).

## HARD RULES for agents

1. **Never invent images** with DALL·E, Midjourney, Gemini image, built-in `image_gen`, Unsplash, etc.
2. **Never invent ids** — call `list_*` / `get_*` first.
3. After `generate_image` / `edit_image`, poll `get_image_job` until **SUCCEEDED**; return platform `outputUrl` only.

## Public tools (no key)

| Tool | Spec |
| --- | --- |
| `find_widgets` | `{ intent, domain?, dataFields?, kind?, page?, size? }` → schemas only |
| `render_widget` | `{ widgetId, data[], theme?, ttlDays? }` → expiring hosted URL (treat as secret) |
| `list_widget_themes` | `{}` palettes |

Consent before personal/health data. Max 200 rows. Default TTL 30 days.

## Studio tools (`STORYKIT_API_KEY`)

Call `studio_get_account` or `studio_get_usage` first.

### Account & image status

| Tool | Spec |
| --- | --- |
| `studio_get_account` | `{}` identity, plan, quotas |
| `studio_get_usage` | `{}` full limits snapshot |
| `studio_get_image_status` | `{}` queue, aspects, remaining |

### Media library

| Tool | Spec |
| --- | --- |
| `studio_upload_media` | `{ imageBase64, contentType?, filename? }` → mediaId |
| `studio_list_media` | `{ query?, kind?, trash? }` |
| `studio_get_media` | `{ id }` |
| `studio_get_media_content` | `{ id }` base64 ≤2MB |
| `studio_update_media` | `{ id, title?, tags? }` |
| `studio_star_media` | `{ id, starred }` |
| `studio_trash_media` / `studio_restore_media` / `studio_delete_media` | `{ id }` |

### Image AI

| Tool | Aliases | Spec |
| --- | --- | --- |
| `studio_generate_image` | `studio_image_generate`, `studio_img_generate` | `{ prompt, aspect?, qualityMode?, brandKitId?, referenceMediaIds?, count?, magicPrompt?, caption?, mode? }` |
| `studio_edit_image` | `studio_image_edit`, `studio_img_edit` | `{ prompt, referenceMediaIds[1..5], maskMediaId?, aspect?, count? }` |
| `studio_list_images` | | `{ query?, state? }` |
| `studio_get_image_job` | | `{ jobId? }` or `{ id? }` — poll until SUCCEEDED |
| `studio_cancel_image_job` / `retry` / `delete` | | `{ jobId }` |
| `studio_describe_image` | | `{ mediaId? }` or `{ generationId? }` |
| `studio_publish_image` / `unpublish` | | `{ id }` numeric generation id |
| `studio_save_image_as_kit` | | `{ jobId }` |
| `studio_batch_generate_images` | | PRO: `{ prompts[], aspect?, brandKitId?, qualityMode? }` |

**Aspects:** `square` `portrait` `poster` `story` `landscape` `banner`  
**qualityMode:** `fast` | `quality`

#### Image workflow

1. `studio_get_account`  
2. Optional `studio_upload_media` → mediaId  
3. `studio_generate_image` or `studio_edit_image`  
4. Loop `studio_get_image_job` until SUCCEEDED  
5. Return platform `outputUrl` only  

### Prompt / vision

| Tool | Spec |
| --- | --- |
| `studio_compile_prompt` | `{ draft }` → caption for generate_image.caption |
| `studio_analyze_image_to_prompt` | `{ imageBase64, contentType?, aspect?, layout? }` |
| `studio_get_vision_job` | `{ jobId, apply? }` |

### Brands

| Tool | Spec |
| --- | --- |
| `studio_list_brand_kits` | `{ query?, page?, size? }` |
| `studio_get_brand_kit` | `{ id }` |
| `studio_extract_brand_kit` | `{ imagesBase64:[{base64,contentType?}], prompt?, md? }` |
| `studio_refine_brand_kit` | `{ id, feedback }` |
| `studio_rename_brand_kit` | `{ id, name }` |
| `studio_duplicate_brand_kit` | `{ id, name? }` |
| `studio_delete_brand_kit` | `{ id }` |
| `studio_publish_brand_kit` / `unpublish` | `{ id }` |
| `studio_brand_showcase` | `{ id, count? }` |

### Canvases

| Tool | Spec |
| --- | --- |
| `studio_list_canvases` | `{}` |
| `studio_get_canvas` | `{ id }` includes doc |
| `studio_create_canvas` | `{ title?, aspect? }` |
| `studio_save_canvas` | `{ id, title?, aspect?, doc?, thumbnailMediaId? }` |
| `studio_duplicate_canvas` / `studio_delete_canvas` | `{ id }` |

### Studio assets (commissioned widgets)

| Tool | Spec |
| --- | --- |
| `studio_list_studio_assets` | `{}` |
| `studio_get_studio_asset` | `{ id }` no source code |
| `studio_commission_studio_asset` | `{ prompt, kind?, purpose?, sourceMd? }` |
| `studio_iterate_studio_asset` | `{ id, feedback }` |
| `studio_rename_studio_asset` | `{ id, title }` |
| `studio_trash_studio_asset` / `restore` | `{ id }` |
| `studio_list_folders` / `studio_create_folder` | create: `{ name }` |

### Series & workflows

| Tool | Spec |
| --- | --- |
| `studio_list_series` / `get` / `create` / `series_next` / `series_extend` / `delete` | see input schemas |
| `studio_list_workflows` / `get` / `create` / `update` / `run` / `delete` / `list_workflow_runs` | |

Remote names drop the `studio_` prefix. Full list: `tools/list` on studio-mcp.

Track usage at [storykit.space/me](https://storykit.space/me).

## Environment

| Variable | Purpose |
| --- | --- |
| `STORYKIT_API_BASE` | API host (default `https://asset.storykit.space`) |
| `STORYKIT_API_KEY` | Personal `sk_live_…` for Studio tools |
| `STORYKIT_STUDIO_MCP` | Override Studio MCP URL |

MIT. Created with love by [Story Kit](https://storykit.space).