Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
ChatGPT MCP App UI
MSO exposes three product presentation resources plus one deliberately minimal Native UI diagnostic probe. Ordinary data tools and workflow startup stay headless; clients without MCP Apps keep structured/text results. The model fetches data first, then chooses List, Block or Page as a separate render step. The probe exists only to distinguish server-side resource binding from ChatGPT host mounting and contains no product routing or interaction logic.
| Surface | Entry tool | Resource | Purpose |
|---|---|---|---|
| List | render_mso_list |
ui://mso/list-v3.html |
Searchable compact collections and item actions |
| Block | render_mso_block |
ui://mso/block-v5.html |
Validation, actions, bounded CRUD input/output |
| Page | render_mso_page, integration_setup_open |
ui://mso/page-v16.html |
Native workspaces, session assets and reviewed project previews |
| Native probe | mso_native_ui_probe |
ui://mso/native-probe-v2.html |
Static diagnostic text only; no bridge, iframe, fetch, router or external dependency |
Layout and identity
Page fills the host's declared containerDimensions.height, or the full
containerDimensions.maxHeight allowance. Legacy window.openai.maxHeight is the
fallback, followed by a 680 px working area when no constraint is supplied. The former
48% cap is removed. Height never derives from the current iframe viewport, preventing
resize feedback. One Page body owns scrolling; fullscreen uses the actual viewport.
Page reports measured dimensions through ui/notifications/size-changed after the
MCP Apps handshake. Legacy hosts can use notifyIntrinsicHeight. The host controls
the enclosing frame and may impose a smaller fixed height. Fullscreen/PiP require an
explicit click and are hidden when the host declares them unsupported.
Standard host context controls theme, display mode, dimensions and safe-area insets.
Standard styles.variables supplies host colors, type, font family and corners; removing an override restores the shared defaults. Legacy OpenAI globals and the browser color-scheme remain compatible fallbacks. Layout responds to the container, including a 320 × 200 viewport; narrow Integrations uses a native service selector instead of a nested scrolling rail.
The compact header, readable controls, flat navigation and shared integration styles
follow the existing MSO workbench. List, Block, Page and native Integrations embed the existing
public/icon.svg mark without an image request; the shell uses that same public asset.
Presentation colors, fonts, type scale, spacing, control size, focus, radii and scroll tokens remain in lib/presentation/widget-tokens.ts.
List behavior
List is a pure presentation tool. The model first calls a normal list/search/read tool, reasons over the returned structured data, and then passes only the selected bounded items to render_mso_list. It accepts at most 40 items, four metadata pairs per item, two item actions and three collection actions. layout is list or grid; optional local search filters only the already-rendered items and makes no network request. Icons are semantic tokens, not arbitrary image URLs.
List actions behave like Block actions: a click sends a bounded follow-up message to ChatGPT with the item id/title and requested continuation. The widget never names or directly calls an MSO mutation tool, so OAuth scope, confirmations, concurrency guards, audit and workflow ownership remain authoritative.
Block behavior
Block accepts bounded structured fields, checks, scalar outputs and up to eight actions; it never accepts raw HTML or an arbitrary tool name. A click sends a bounded follow-up message containing the selected action and field values. The agent then uses ordinary scoped tools. Server authorization, validation, rate limits and audit remain authoritative. Private widget state contains current form values. Block has no network or frame allowlist.
Page routes and trust
| Route | Context / behavior |
|---|---|
/ |
Workspace navigation |
/integrations |
Shared connection manager, Add MCP and private credential forms |
/monitor |
Bounded server status through vps_status |
/project |
Explicit project context; project_get |
/diff |
Explicit project and optional SHA; project_diff |
/sessions |
Latest 50 safe saved conversation summaries belonging to the authenticated MCP client |
/assets |
Paginated private session assets and bounded image/JSON previews through existing artifact tools |
/browser |
Open the MSO remote browser |
/apps/<reviewed-id> |
Reviewed sandboxed iframe preview, or explicit remote-browser handoff |
Page mounts a nested frame only for an owner-reviewed registry row with renderer:"iframe". It accepts neither arbitrary HTML nor external URLs from the model. The bounded owner registry (~/.mso/surface-apps.json, or the explicit
MSO_SURFACE_APPS_JSON override) supplies app identity, HTTPS origin and approved path.
Public source defaults to an empty app catalog. Resource reads rebuild this safe catalog;
the browser rechecks app identity, origin and path before mounting or opening it. Resource HTML and frame CSP are built from the same snapshot. Optional project identifies the reviewed project; a conflicting context fails explicitly. Sandbox tokens come only from that snapshot, default to allow-scripts, and exclude top navigation. The cockpit/widget origin is always remote-only. Preview failure exposes Open preview / MSO Browser without stripping frame headers or passing MSO credentials.
Native integration forms and tools use the same capability/connection contracts as the browser. Credentials travel directly to MSO using private, expiring setup authorization, never through chat or ordinary tool arguments. Public guides remain readable without write access. Project MCP and automation contracts are in automation flows.
User-installed HTML apps cannot grant themselves Page trust. The authenticated cockpit retains its framing protections; external sites keep their own authentication boundaries.
Bridge, metadata and compatibility
The MCP transport advertises the standard io.modelcontextprotocol/ui extension with
mimeTypes: ["text/html;profile=mcp-app"] in both legacy initialize and modern
server/discover. A native host must advertise the matching extension/MIME in its
client capabilities for MCP Apps presentation to be negotiated. Without that bilateral
capability, MSO remains usable as a normal structured/text MCP server instead of
assuming that a ui.resourceUri descriptor alone proves host support.
For host-boundary debugging, the owner-private MCP activity stream records
protocol.initialize / protocol.discover with client-ui=true|false plus
resources.list / resources.read URI, MIME, result state and duration. It never
records the resource HTML itself. This makes a missing host resource fetch observable
without exposing widget bytes, OAuth material or tool arguments.
Page initializes MCP Apps protocol 2026-01-26, then sends
ui/notifications/initialized. Only parent-source messages are accepted. Tool result
notifications and legacy wrapped window.openai.toolOutput use the same route validator.
Unchanged outputs do not remount views; teardown clears active forms and observers.
List, Block and Page use the standards-first MCP Apps bridge (ui/initialize, tool-result notifications and ui/message/tools/call where applicable). Their render tools keep _meta.ui.resourceUri as the canonical MCP Apps binding and also mirror it into the compatibility _meta["ui/resourceUri"] key used by the official ext-apps registration helper. resources/list preserves each canonical resource's _meta.ui listing metadata instead of stripping it, so hosts can index the same UI contract before resources/read. Block additionally retains its existing ChatGPT openai/outputTemplate compatibility binding; the other surfaces do not. The Native UI probe remains dependency-free static HTML, but now uses the same descriptor compatibility normalization as the product surfaces. Every ChatGPT tool has an output schema; exact tools, counts and scopes are generated in the catalog.
Resource CSP is explicit: Block allows no nested frames; Page includes only exact reviewed iframe origins and permits its MSO origin for private setup requests. OpenAI requires stricter review for frameDomains; this is an official review boundary, not a blanket iframe ban. OS_MCP_UI_ORIGIN controls the widget origin, otherwise
the configured public origin derives it. Legacy redirect metadata supports Open in MSO.
The three product resources and the isolated Native UI diagnostic probe are listed. Immediately previous canonical URIs remain read aliases after a cache-busting release (list-v2, block-v4, page-v15, native-probe-v1), together with the older compatibility aliases. Only the newest canonical URIs are advertised by resources/list. workflow_status and render_mso_surface remain app-only compatibility tools. workflow_start has no UI binding.
Verification and deployment
Run node scripts/e2e/mcp-page.mjs for a small initial host frame, standard-versus-legacy
height precedence, fixed/flexible resize, light/dark theme, 280–1280 px widths and 320 × 200 layouts, logo,
Add MCP, native sessions/assets/monitor, host design tokens, interactive sandboxed demos, WCAG checks and fullscreen. The release gate runs this browser contract automatically.
node scripts/e2e/integrations.mjs adds shared manager user CRUD, keyboard selection,
provider search and 320–1920 px reflow. Production release journeys verify authorization,
real server handlers and provider revocation using synthetic stores.
After shipping, compare live discovery/version/hash against lib/mcp/toolset.ts and the generated catalog, verify the three product resource URIs plus ui://mso/native-probe-v2.html, call mso_native_ui_probe from a directly selected registered app context, render a List, and reopen the Page. Also inspect the browser network request to /backend-api/ecosystem/widget: success requires that ChatGPT resolves the current template_pointer instead of returning 404. Hosts cache tool and resource descriptors, so a development-app Scan Tools/Refresh and a new conversation are required after a canonical URI/toolset change. The server cannot replace an already mounted document in an old conversation.
Official references:
Per-installation registered app binding
Native MSO UI must be invoked through the registered ChatGPT MCP App rather than a nested function wrapper. Each MSO installation therefore keeps its registered OpenAI App ID in the owner-private OpenAI / ChatGPT App Integrations connection. The public source repository does not contain the maintainer's App ID.
Users get their own ID by enabling ChatGPT developer mode, registering their MSO remote MCP endpoint, completing tool scan/OAuth, and copying the App ID from app details (or the equivalent plugin_asdk_app_... technical ID from the browser URL). The private staging command writes canonical asdk_app_... only into the owner-private package. Version IDs are version-scoped metadata; MSO intentionally does not store or use them.