Watch

Jonathan Hefner 78b24ae2ac Add skeleton docs/patterns.md with type-checked companion file

Introduces a patterns documentation page for common MCP Apps recipes.
The skeleton includes TODO sections for: perceived latency, iframe/MCP Apps
coexistence, authenticated calls, private tools, theme changes, fullscreen,
host styling, data persistence, OpenAI migration, and error handling.

- Add `docs/patterns.md` to `projectDocuments` in `typedoc.config.mjs`
- Add `docs/patterns.ts` companion file with region-delimited code stubs
- Include `docs/**/*.ts` in `tsconfig.json` for type-checking
- Document the standalone docs pattern in `CLAUDE.md`

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

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

2.5 KiB

Raw Blame History

title
Patterns

MCP Apps Patterns

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

[TODO] Tools that are private to Apps

Use Tool._meta.ui.visibility: ["apps"] to make tools only visible to Apps.

{@includeCode ./patterns.ts#privateTools}

[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.ts#authenticatedCalls}

[TODO] Giving errors back to model

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

{@includeCode ./patterns.ts#errorsToModel}

[TODO] Support native host styling / use CSS variables

{@includeCode ./patterns.ts#hostStyling}

[TODO] Reacting to light/dark theme changes

{@includeCode ./patterns.ts#lightDarkTheme}

[TODO] Support fullscreen / exit fullscreen

{@includeCode ./patterns.ts#fullscreen}

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.ts#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.ts#lowerPerceivedLatency}

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

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

{@includeCode ./patterns.ts#iframeAndMcpApps}

[TODO] Migrating from OpenAI to MCP Apps

See OpenAI -> MCP Apps migration guide.

Also: Managing State (OpenAI)

{@includeCode ./patterns.ts#migrateFromOpenai}

2.5 KiB Raw Blame History