App

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

What it is#

The app's metadata is id, name, handle, optional customSubdomain / customDomain, description, and SEO defaults (defaultOgImage, faviconUrl, siteTitleSuffix). Pages belong to the app but are listed separately (list_pages) — they are not embedded on the app record.

packages/modules/app/core/src/domain/app.model.types.ts

Every app has a handle (<handle>.codelab.app). That is the guaranteed URL. An admin-granted customSubdomain overrides the handle on the same apex; a customDomain (your host) wins over both. TLS for a custom domain shows as customDomainStatus: "pending" while the cert issues, "active" once live, null if none.

packages/modules/app/core/src/domain/published-url.ts

create_app does not leave an empty shell. It persists the app, a default Home page (isHome: true, routePattern: ""), a chat, variant presets, and heading kind styles.

packages/modules/app/server/src/services/create-app.service.ts

An app must keep at least one page. Home is the page flagged isHome, else the first page.

packages/modules/app/core/src/domain/app.model.ts

How it relates#

packages/modules/store/core/src/domain/store.model.ts packages/modules/mcp/server/src/theme-token.mcp.ts

Hooks, reusable schemas, and env vars are also app-scoped (packages/modules/mcp/server/src/hook.mcp.ts, schema.mcp.ts). 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.

packages/modules/mcp/server/src/app.mcp.ts packages/modules/mcp/server/src/context.mcp.ts

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" \| "Component", id } instead of appId. Ownership is checked from that id, not from context — but you still need context to find those ids.

packages/modules/mcp/server/src/mcp-ownership.service.ts

Typical first calls:

list_apps
set_context  { appId }
get_context  { contextId }     # confirm
list_pages   { contextId }     # 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 until set_context. Retain contextId; do not expect a hidden session app. (packages/modules/mcp/server/src/context.mcp.ts)
• create_app already made Home. Do not create_page for the landing page. list_pages first. (packages/modules/app/adapter/src/ai/create-app.tool.ts)
• 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 CVA does not set. Per-element style_* is last. Token keys are fixed — you change values, not names. (packages/modules/mcp/server/src/theme-token.mcp.ts)
• previewData is builder-only. Sample {{session.*}} for the canvas. The published site never reads it. (packages/modules/app/core/src/domain/app.model.types.ts)
• delete_app is total. Every page, element, and store goes with it. (packages/modules/app/adapter/src/ai/delete-app.tool.ts)