Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/migrate_from_openai_apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,9 +265,9 @@ Client-side migration involves replacing the implicit `window.openai` global wit
| -------------------------------------------------- | --------------------------------------------------------- | ----------------------------------- |
| `await window.openai.requestDisplayMode({ mode })` | `await app.requestDisplayMode({ mode })` | Same API |
| — | Check `app.getHostContext()?.availableDisplayModes` first | MCP lets you check what's available |
| `_meta["openai/ui"].preferredDisplayMode` | `preferredDisplayMode` in the `App` capabilities | A hint; see below |
| `_meta["openai/ui"].preferredDisplayMode` | `_meta.ui.preferredDisplayMode` on the UI resource | A hint; see below |

`_meta["openai/ui"].preferredDisplayMode` comes from OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md#display-modes), where it is set on the UI resource. In MCP Apps the View declares the preference itself when it connects (`new App(appInfo, { availableDisplayModes, preferredDisplayMode })`), and the host may ignore it.
`_meta["openai/ui"].availableDisplayModes` and `preferredDisplayMode` come from OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md#display-modes). MCP Apps uses the same names in the same place, the UI resource content item, under `_meta.ui` instead of `_meta["openai/ui"]`. The host may ignore the preference.

### Size Reporting

Expand Down
36 changes: 24 additions & 12 deletions docs/patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,23 +447,35 @@ In fullscreen mode, remove the container's border radius so content extends to t
}
```

If your View is mainly useful on a large surface, declare `fullscreen` as its preferred display mode. This is a hint for how the host first shows the View. The host may ignore it, or apply it just after the View is first shown, so keep the `onhostcontextchanged` handler above:
If your View is mainly useful on a large surface, declare `fullscreen` as its preferred display mode on the UI resource. The host reads it before the View loads, so it can open the View in fullscreen right away. It is a hint: the host may ignore it, or apply it just after the View is first shown, so keep the `onhostcontextchanged` handler above:

<!-- prettier-ignore -->
```ts source="../src/app.examples.ts#App_constructor_preferredDisplayMode"
const app = new App(
{ name: "MyApp", version: "1.0.0" },
```ts source="../src/server/index.examples.ts#registerAppResource_preferredDisplayMode"
registerAppResource(
server,
"Map",
"ui://map/view.html",
{
availableDisplayModes: ["inline", "fullscreen"],
preferredDisplayMode: "fullscreen",
description: "Interactive map",
},
async () => ({
contents: [
{
uri: "ui://map/view.html",
mimeType: RESOURCE_MIME_TYPE,
text: mapHtml,
_meta: {
ui: {
// Known before the View loads, so the host can open it in fullscreen
// right away. A hint: the host may still show it inline.
availableDisplayModes: ["inline", "fullscreen"],
preferredDisplayMode: "fullscreen",
},
},
},
],
}),
);
await app.connect();

// The host may ignore the preference: read the actual mode.
const container = document.getElementById("main")!;
const isFullscreen = app.getHostContext()?.displayMode === "fullscreen";
container.classList.toggle("fullscreen", isFullscreen);
```

> [!NOTE]
Expand Down
44 changes: 22 additions & 22 deletions examples/basic-host/src/implementation.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, type McpUiDisplayMode, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
import {
Client,
SSEClientTransport,
Expand Down Expand Up @@ -76,6 +76,8 @@ interface UiResourceData {
html: string;
csp?: McpUiResourceCsp;
permissions?: McpUiResourcePermissions;
availableDisplayModes?: McpUiDisplayMode[];
preferredDisplayMode?: McpUiDisplayMode;
}

export interface ToolCallInfo {
Expand Down Expand Up @@ -155,8 +157,10 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
const uiMeta = contentMeta?.ui ?? listingMeta?.ui;
const csp = uiMeta?.csp;
const permissions = uiMeta?.permissions;
const availableDisplayModes = uiMeta?.availableDisplayModes;
const preferredDisplayMode = uiMeta?.preferredDisplayMode;

return { html, csp, permissions };
return { html, csp, permissions, availableDisplayModes, preferredDisplayMode };
}


Expand Down Expand Up @@ -409,25 +413,21 @@ export function newAppBridge(
return { mode: newMode };
};

// Honor `appCapabilities.preferredDisplayMode`. It is a hint for how the
// app is first shown, so apply it once, as soon as the app has initialized
// (a repeated `ui/initialize` does not renew it). This host starts every
// app inline and offers only inline and fullscreen, so fullscreen is the
// one preference to act on, and only if the app also lists it as available.
const applyPreferredDisplayMode = () => {
appBridge.removeEventListener("initialized", applyPreferredDisplayMode);
const caps = appBridge.getAppCapabilities();
if (
caps?.preferredDisplayMode === "fullscreen" &&
caps.availableDisplayModes?.includes("fullscreen") &&
(options?.displayMode ?? "inline") === "inline"
) {
log.info("Applying the app's preferred display mode: fullscreen");
appBridge.sendHostContextChange({ displayMode: "fullscreen" });
callbacks?.onDisplayModeChange?.("fullscreen");
}
};
appBridge.addEventListener("initialized", applyPreferredDisplayMode);

return appBridge;
}


/**
* Choose how to first show the app, from its resource's `_meta.ui` display
* mode hints. This host offers only inline and fullscreen, so fullscreen is
* the one preference to act on, and only if the resource lists it as available
* (or lists no modes).
*/
export function initialDisplayMode(
{ availableDisplayModes, preferredDisplayMode }: UiResourceData,
): "inline" | "fullscreen" {
return preferredDisplayMode === "fullscreen" &&
(availableDisplayModes?.includes("fullscreen") ?? true)
? "fullscreen"
: "inline";
}
10 changes: 7 additions & 3 deletions examples/basic-host/src/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol
import type { Tool } from "@modelcontextprotocol/client";
import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
import { createRoot } from "react-dom/client";
import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
import { callTool, connectToServer, hasAppHtml, initialDisplayMode, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
import { getTheme, toggleTheme, onThemeChange, type Theme } from "./theme";
import styles from "./index.module.css";

Expand Down Expand Up @@ -434,21 +434,25 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI

// First get CSP and permissions from resource, then load sandbox
// CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute
toolCallInfo.appResourcePromise.then(({ csp, permissions }) => {
toolCallInfo.appResourcePromise.then((resource) => {
const { csp, permissions } = resource;
loadSandboxProxy(iframe, csp, permissions).then((firstTime) => {
// The `firstTime` check guards against React Strict Mode's double
// invocation (mount → unmount → remount simulation in development).
// Outside of Strict Mode, this `useEffect` runs only once per
// `toolCallInfo`.
if (firstTime) {
// Apply the resource's display mode hints before the app is shown.
const firstMode = initialDisplayMode(resource);
setDisplayMode(firstMode);
const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe, {
onContextUpdate: setModelContext,
onMessage: (msg) => setMessages((prev) => [...prev, msg]),
onDisplayModeChange: setDisplayMode,
}, {
// Provide container dimensions - maxHeight for flexible sizing
containerDimensions: { maxHeight: 6000 },
displayMode: "inline",
displayMode: firstMode,
});
appBridgeRef.current = appBridge;
initializeApp(iframe, appBridge, toolCallInfo);
Expand Down
73 changes: 46 additions & 27 deletions specification/draft/apps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,25 @@ interface UIResourceMeta {
* - omitted: host decides border
*/
prefersBorder?: boolean,
/**
* Display modes the view supports
*
* Same meaning as `appCapabilities.availableDisplayModes` (see Display Modes),
* but known before the view loads, so the host can choose how it first shows it.
*
* @example
* ["inline", "fullscreen"]
*/
availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">,
/**
* Display mode in which the view prefers to be first shown
*
* A hint: the host MAY ignore it. See Display Modes section for details.
*
* @example
* "fullscreen"
*/
preferredDisplayMode?: "inline" | "fullscreen" | "pip",
}
```

Expand Down Expand Up @@ -254,6 +273,8 @@ The resource content is returned via `resources/read`:
};
domain?: string;
prefersBorder?: boolean;
availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">;
preferredDisplayMode?: "inline" | "fullscreen" | "pip";
};
};
}];
Expand All @@ -262,7 +283,7 @@ The resource content is returned via `resources/read`:

#### Metadata Location

`UIResourceMeta` (CSP, permissions, domain, prefersBorder) may be provided on either or both:
`UIResourceMeta` (CSP, permissions, domain, prefersBorder, availableDisplayModes, preferredDisplayMode) may be provided on either or both:

- **`resources/list`:** On the resource entry's `_meta.ui` field. Useful as a static default that hosts can review at connection time.
- **`resources/read`:** On each content item's `_meta.ui` field. Useful for per-response overrides or dynamic metadata that is only known at read time.
Expand Down Expand Up @@ -560,12 +581,6 @@ interface McpUiAppCapabilities {
* @example ["inline", "fullscreen"]
*/
availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">;
/**
* Display mode in which the app prefers to be first shown. A hint: the host MAY ignore it.
* See Display Modes section for details.
* @example "fullscreen"
*/
preferredDisplayMode?: "inline" | "fullscreen" | "pip";
}
```

Expand Down Expand Up @@ -843,27 +858,30 @@ Hosts declare which display modes they support in `HostContext.availableDisplayM

#### Preferred Display Mode

A View can name the display mode in which it prefers to be first shown, in `appCapabilities.preferredDisplayMode`. This suits Views that are mainly useful on a large surface, such as an editor, a dashboard or a map.
A UI resource can declare the display modes its View supports and the one in which it prefers to be first shown, in `_meta.ui.availableDisplayModes` and `_meta.ui.preferredDisplayMode`. Both follow the [Metadata Location](#metadata-location) rules. They are on the resource rather than in `ui/initialize` so that a Host can choose how it first shows the View before the View has loaded, and the user does not see it move. This suits Views that are mainly useful on a large surface, such as an editor, a dashboard or a map.

```typescript
// Example: View supports inline and fullscreen, and prefers to start in fullscreen
```json
// resources/read content item: View supports inline and fullscreen, and prefers to start in fullscreen
{
method: "ui/initialize",
params: {
appCapabilities: {
availableDisplayModes: ["inline", "fullscreen"],
preferredDisplayMode: "fullscreen"
},
// ...
"uri": "ui://map-server/map",
"mimeType": "text/html;profile=mcp-app",
"text": "<!DOCTYPE html><html>...</html>",
"_meta": {
"ui": {
"availableDisplayModes": ["inline", "fullscreen"],
"preferredDisplayMode": "fullscreen"
}
}
}
```

The preference is a hint. The Host chooses how it first shows the View and how much weight it gives to the preference, for example when several Views prefer `fullscreen` at once. The View sends the preference before it has seen `HostContext.availableDisplayModes`, so checking that the mode is available falls to the Host.
The preference is a hint. The Host chooses how it first shows the View and how much weight it gives to the preference, for example when several Views prefer `fullscreen` at once.

A Host that applies the preference should do so before it first shows the View, and tells the View in the `hostContext.displayMode` of its `ui/initialize` result. A Host that has already shown the View, for example inline while the tool runs, may instead move it once, no later than when it sends the first `ui/notifications/tool-result`. After that, a Host should not use the preference to move the View without a user action: to change mode later, Views use `ui/request-display-mode`.

A Host that applies the preference should do so before it first shows the View, so that the user does not see the View move. It tells the View either in the `hostContext.displayMode` of its `ui/initialize` result, or in a `ui/notifications/host-context-changed` sent after `ui/notifications/initialized`. A Host that has already shown the View, for example inline while the tool runs, may instead move it once, no later than when it sends the first `ui/notifications/tool-result`. After that, a Host should not use the preference to move the View without a user action: to change mode later, Views use `ui/request-display-mode`.
Once the View has initialized, `appCapabilities.availableDisplayModes` is authoritative. A View that declares display modes on its resource SHOULD declare the same list there.

Note (non-normative): the name and the meaning of this field follow OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/15e0f4745e7c95865ee2195de5b79f4148b21418/docs/spec.md#display-modes), which define `_meta["openai/ui"].preferredDisplayMode` as the preferred initial display mode. There it is on the UI resource content item rather than in `ui/initialize`; this specification does not define that key.
Note (non-normative): these fields follow OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/39f91ad0bdf1435aadb879172ab2467d0e97cead/docs/spec.md#display-modes), which define `availableDisplayModes` and `preferredDisplayMode` under `_meta["openai/ui"]` on the UI resource content item. This specification does not define that key.

#### Requesting Changes

Expand All @@ -879,19 +897,20 @@ Hosts notify views of display mode changes via `ui/notifications/host-context-ch
- View MUST declare all display modes it supports in `appCapabilities.availableDisplayModes` during initialization.
- View MUST check if the requested mode is in `availableDisplayModes` from host context before requesting a mode change.
- View MUST handle the response mode differing from the requested mode.
- View that sets `appCapabilities.preferredDisplayMode` MUST also list that mode in `appCapabilities.availableDisplayModes`.
- View MUST handle being shown in a display mode other than `appCapabilities.preferredDisplayMode`.
- A UI resource that sets both `_meta.ui.preferredDisplayMode` and `_meta.ui.availableDisplayModes` MUST list the preferred mode in `availableDisplayModes`.
- View MUST handle being shown in a display mode other than its resource's `_meta.ui.preferredDisplayMode`.

**Host behavior:**
- Host MUST NOT switch the View to a display mode that does not appear in its `appCapabilities.availableDisplayModes`, if set.
- Host MUST return the resulting mode (whether updated or not) in the response to `ui/request-display-mode`.
- If the requested mode is not available, Host SHOULD return the current display mode in the response.
- Host MAY decline display mode requests from Views that did not declare said modes in their capabilities.
- Host MAY ignore `appCapabilities.preferredDisplayMode`, for example in favor of a choice the user has made, or by declining to start a View in `fullscreen` or `pip` without a user action.
- Host MUST NOT refuse `ui/initialize` because it does not offer the preferred mode (one of the display modes defined above), or because `appCapabilities.availableDisplayModes`, if set, lacks it; it ignores the preference instead.
- Host that applies `appCapabilities.preferredDisplayMode` SHOULD do so before it first shows the View. A Host that has already shown the View MAY instead apply it once, no later than when it sends the first `ui/notifications/tool-result`, unless the user has changed the View's display mode in the meantime.
- After that, Host SHOULD NOT use the preference to change the View's display mode without a user action. A repeated `ui/initialize` from a View that is already shown does not renew the preference.
- Host that applies `appCapabilities.preferredDisplayMode` SHOULD report the resulting mode in `hostContext.displayMode`.
- Host MAY ignore `_meta.ui.preferredDisplayMode`, for example in favor of a choice the user has made, or by declining to start a View in `fullscreen` or `pip` without a user action.
- Host MUST ignore `_meta.ui.preferredDisplayMode` if the resource's `_meta.ui.availableDisplayModes` is set and does not list it.
- Host that chose a display mode from the resource's `_meta.ui` before the View initialized, and finds that mode missing from `appCapabilities.availableDisplayModes`, SHOULD move the View to a mode that list includes and report it in `ui/notifications/host-context-changed`.
- Host that applies `_meta.ui.preferredDisplayMode` SHOULD do so before it first shows the View. A Host that has already shown the View MAY instead apply it once, no later than when it sends the first `ui/notifications/tool-result`, unless the user has changed the View's display mode in the meantime.
- After that, Host SHOULD NOT use the preference to change the View's display mode without a user action. Re-reading the resource for a View that is already shown does not renew the preference.
- Host that applies `_meta.ui.preferredDisplayMode` SHOULD report the resulting mode in `hostContext.displayMode`.

### Theming

Expand Down
Loading