Watch

Jonathan Hefner dce143e92e Complete "Entering / exiting fullscreen" pattern documentation

Add `App_onhostcontextchanged_respondToDisplayMode` example showing how to
listen for display mode changes and update UI with `classList.toggle()`.

Update `App_requestDisplayMode_fullscreen` to `App_requestDisplayMode_toggle`
to show the common toggle pattern checking `availableDisplayModes` first.

Refactor full examples (pdf-server, shadertoy-server) to use
`classList.toggle(class, condition)` instead of add/remove branches.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-20 13:31:11 -06:00

3.4 KiB

Raw Blame History

title
Patterns

MCP Apps Patterns

This document covers common patterns and recipes for building MCP Apps.

Tools that are private to Apps

Set {@link types!McpUiToolMeta.visibility Tool._meta.ui.visibility} to ["app"] to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating quantities, toggling settings, or other interactions that shouldn't appear in the model's tool list.

{@includeCode ../src/server/index.examples.ts#registerAppTool_appOnlyVisibility}

[TODO] Authenticated calls from App

Use tool calls / read resources
- See PDF example to read binaries by chunks to avoid call tool size limitations on platforms like claude.ai
Pass auth token in _meta (will be loaded again in the future) + refresh token + store in local storage (see Persist data section below)

{@includeCode ./patterns.tsx#authenticatedCalls}

[TODO] Giving errors back to model

Before app runs: validate inputs in tool call
After it runs: use updateModelContext

{@includeCode ./patterns.tsx#errorsToModel}

Matching host styling (CSS variables, theme, and fonts)

Use the SDK's style helpers to apply host styling, then reference them in your CSS:

CSS variables — Use var(--color-background-primary), etc. in your CSS
Theme — Use [data-theme="dark"] selectors or light-dark() function for theme-aware styles
Fonts — Use var(--font-sans) or var(--font-mono) with fallbacks (e.g., font-family: var(--font-sans, system-ui, sans-serif))

Vanilla JS:

{@includeCode ./patterns.tsx#hostStylingVanillaJs}

React:

{@includeCode ./patterns.tsx#hostStylingReact}

Entering / Exiting fullscreen

Toggle fullscreen mode by calling {@link app!App.requestDisplayMode requestDisplayMode}:

{@includeCode ../src/app.examples.ts#App_requestDisplayMode_toggle}

Listen for display mode changes via {@link app!App.onhostcontextchanged onhostcontextchanged} to update your UI:

{@includeCode ../src/app.examples.ts#App_onhostcontextchanged_respondToDisplayMode}

Note: OAI's window.openai.setWidgetState({modelContent, privateContent, imageIds}) has only a partial equivalent in the MCP Apps spec (for now!): App.updateModelContext({content, structuredContent})
For data persistence / to reload when conversation is reloaded, you must use localStorage / IndexedDb with hostInfo.toolInfo.id as key returned CallToolResult._meta.widgetUUID = randomUUID()

{@includeCode ./patterns.tsx#persistData}

[TODO] Lower perceived latency / manage loading time

Leverage partial inputs to show widgets as possible.

Beware of partial JSON being partial (but healed), so some of your objects may not be complete (e.g. in a list you may need to skip the last item if your code validates input schemas strictly).

{@includeCode ./patterns.tsx#lowerPerceivedLatency}

[TODO] Supporting both iframe & MCP Apps in same binary

See recipe: https://github.com/modelcontextprotocol/ext-apps/issues/34

{@includeCode ./patterns.tsx#iframeAndMcpApps}

[TODO] Migrating from OpenAI to MCP Apps

See OpenAI -> MCP Apps migration guide.

Also: Managing State (OpenAI)

{@includeCode ./patterns.tsx#migrateFromOpenai}

3.4 KiB Raw Blame History