App
The workspace that owns pages, components, stores, and theme.
An App is the unit you build against on the hosted MCP (https://mcp.codelab.app/mcp). It is identity, published URL, and the parent of every page, component, store, and theme token in the project.
Nothing on the canvas exists outside that app. Element trees hang off pages and components the app owns; stores, hooks, schemas, env vars, and theme rules are app-scoped too.
App
├── Pages routed element trees
├── Components reusable element trees + fields
├── Stores runtime state (app-wide or attached to a page/component)
└── Theme tokens + kind styles
Fields
Pages belong to the app but are listed separately (list_pages) — they are not nested on the app record.
| Name | Type | Default | Description |
|---|---|---|---|
id | string | — | App id. Pass this to set_context. |
name | string | — | Display name. |
handle | string | — | Guaranteed URL: <handle>.codelab.app. |
customSubdomain | string | — | Admin-granted subdomain on the same apex; overrides the handle. |
customDomain | string | — | Your own host; wins over handle and subdomain. |
customDomainStatus | "pending" | "active" | empty | empty | TLS for a custom domain: pending while the cert issues, active once live. |
description | string | — | Optional summary. |
defaultOgImage | string | — | Default Open Graph image. |
faviconUrl | string | — | Favicon. |
siteTitleSuffix | string | — | Appended to page titles. |
create_app does not leave an empty shell. It creates the app, a default Home page (isHome: true, routePattern: ""), a chat, variant presets, and heading kind styles.
An app must keep at least one page. Home is the page flagged isHome, else the first page.
How it relates
| Child | Role |
|---|---|
| Page | A routed tree visitors hit. Shared chrome lives on a layout page, not copied onto every leaf. |
| Component | A reusable tree. Place one on a page as an element whose kind is { _tag: "Component", value: componentId }. |
| Element | A node inside a page or component. The app never owns an element directly. |
| Store | Named runtime state. App-wide when unscoped; attach to a page or component so the name can be a plain state per owner. Store actions[] are Action chains. |
| Theme | App-level tokens (theme_tokens) and kind styles (style_rules). Brand here before per-element style_*. |
Hooks, reusable schemas, and env vars are also app-scoped. Hook methods bind as "<hookId>.<method>" actions; field shapes are the type system.
MCP tools
Connect to https://mcp.codelab.app/mcp. App CRUD addresses the app by id (you can only touch your own). Everything else that lists or mutates inside an app needs a conversation context.
| Tool | What you use it for |
|---|---|
list_apps | Discover appId, name, subdomain, domain, customDomainStatus. Call this before set_context. |
set_context | Activate an app. Omit contextId on the first call; keep the returned contextId and pass it to every app-scoped tool. Send the same id when switching apps. |
get_context | Verify the active app. |
clear_context | Drop this conversation's handle. |
create_app | { name, description? } — scaffolds Home + chat + presets. Then set_context with the new appId. |
update_app | Partial metadata (name, description, customDomain, SEO defaults). Omitted fields stay. customSubdomain is admin-only. |
delete_app | Cascades pages, elements, stores, … Irreversible. If it was the active context, set_context again. |
App-scoped follow-ups (all take contextId): list_pages, list_components, list_stores, list_hooks, list_schemas, list_env_vars, list_theme_tokens, list_theme_styles.
Element tools take a container ({ _tag: "Page", id } or { _tag: "Component", id }) instead of appId. Ownership is checked from that id, not from context — but you still need context to find those ids.
Typical first calls: list_apps → set_context with an appId → get_context to confirm → list_pages (Home is already there).
Gotchas
- No context, no canvas.
list_pages,create_store,add_element(once you need a page id), and the rest fail untilset_context. KeepcontextId; there is no hidden session app. create_appalready made Home. Do notcreate_pagefor the landing page.list_pagesfirst.- Theme before elements. Tokens (
list_theme_tokens/update_theme_tokens) restyle every Button and Card. Kind styles (list_theme_styles/update_theme_style) cover extras the theme does not set. Per-elementstyle_*is last. Token keys are fixed — you change values, not names. previewDatais builder-only. Sample{{session.*}}for the canvas. The published site never reads it.delete_appis total. Every page, element, and store goes with it.