Requesting Display Mode Transitions in MCP Apps (November 2026)

MCP App resources can request display mode transitions directly from user interactions.
An MCP App often starts as a compact card and then needs more room for a table, editor, map, or dashboard. Display mode requests let the app ask its host to move between inline, fullscreen, and picture-in-picture without reloading the resource.
The request is one step in a four-part contract. The app declares which modes it can render, the host advertises which modes it offers, the app asks, and the host decides which mode it actually applies. Code that skips any of those steps ships dead buttons, or layouts that break in the next host.
The same MCP Apps contract applies when a resource runs as a ChatGPT App or as an interactive Claude Connector. Each host and surface can advertise a different mode set, so check capabilities at runtime instead of checking host names.
TL;DR: Show a mode control only when the host lists that mode. In sunpeak, call requestDisplayMode('fullscreen'); with the raw SDK, call app.requestDisplayMode({ mode: 'fullscreen' }) and read result.mode. A declined request usually resolves with the old mode instead of throwing, so render from the host-applied mode (useDisplayMode()), expect the host to change modes on its own, and test the declined path too.
The Three MCP App Display Modes
The stable MCP Apps specification (2026-01-26) defines three values. The current draft spec keeps the same three values and the same rules.
| Mode | What the host does | Good uses |
|---|---|---|
inline | Embeds the app in the conversation flow (the default) | Summaries, cards, compact results, entry points |
fullscreen | Gives the app the full host window or screen | Editors, maps, large tables, multi-step forms |
pip | Places the app in a floating picture-in-picture overlay | Timers, media, live status, reference views |
These names describe presentation, not pixel sizes. A fullscreen app still needs to read container dimensions and safe area insets, a PiP window can be narrow, and an inline card can grow only within host limits. The host context guide covers those layout inputs, and the ChatGPT App display mode reference goes deeper on layout patterns for each mode.
What the Spec Requires
The display mode section of the spec is short, but each rule changes how you write the client code:
| Who | Rule | What it means for your code |
|---|---|---|
| View | MUST declare all supported modes in appCapabilities.availableDisplayModes | Send the list during ui/initialize |
| View | MUST check availableDisplayModes in host context before requesting a mode | Hide controls for modes the host does not list |
| View | MUST handle a response mode that differs from the requested mode | Never assume the request worked |
| Host | MUST NOT switch the View to a mode missing from the View’s declared list, if one is set | Declaring ['inline'] locks the app inline |
| Host | MUST return the resulting mode, changed or not | result.mode is the truth for that request |
| Host | SHOULD return the current mode when the requested mode is unavailable | A declined request usually resolves, it does not reject |
| Host | MAY decline requests for modes the View did not declare | An undeclared mode can fail even when the host offers it |
The flow on the wire looks like this:
- The app sends
ui/initializewithappCapabilities.availableDisplayModes. - The host returns
hostContext.displayModeandhostContext.availableDisplayModes. - The app sends
ui/request-display-modewith{ mode }. - The host responds with
{ mode }set to the mode it applied, and sendsui/notifications/host-context-changedwith the newdisplayModewhen the mode changes.
Host context notifications are partial updates. The View merges the fields it receives into the context it already has, so a notification that only carries displayMode does not wipe out theme or safe area values.
Request a Display Mode with the MCP Apps SDK
With @modelcontextprotocol/ext-apps 2.0.4, the second constructor argument holds the app’s capabilities, including its display modes:
import { App } from '@modelcontextprotocol/ext-apps';
const app = new App(
{ name: 'report-viewer', version: '1.0.0' },
{ availableDisplayModes: ['inline', 'fullscreen'] }
);
await app.connect();
async function expand() {
const context = app.getHostContext();
if (!context?.availableDisplayModes?.includes('fullscreen')) return;
const result = await app.requestDisplayMode({ mode: 'fullscreen' });
if (result.mode !== 'fullscreen') {
// Declined. The host kept (or chose) result.mode.
showNotice('Fullscreen is not available right now.');
}
}
Call requestDisplayMode only after connect() finishes. Before the ui/initialize handshake completes, ext-apps 2.x logs a warning for host-bound calls by default, and throws if you pass { strict: true } in the third constructor argument. The SDK notes that throwing will become the default in a future release, so it is worth turning on now to catch early calls in tests.
Request Display Modes in React with sunpeak
sunpeak gives React resources two focused hooks:
useDisplayMode()returns the current host-applied mode and re-renders when the host changes it.useRequestDisplayMode()returnsrequestDisplayMode(mode)andavailableModes, which comes fromhostContext.availableDisplayModes.
The hook takes the mode as a string:
import { useDisplayMode, useRequestDisplayMode } from 'sunpeak';
export function ExpandButton() {
const displayMode = useDisplayMode();
const { requestDisplayMode, availableModes } = useRequestDisplayMode();
const canFullscreen = availableModes?.includes('fullscreen') ?? false;
if (!canFullscreen || displayMode === 'fullscreen') {
return null;
}
return (
<button type="button" onClick={() => requestDisplayMode('fullscreen')}>
Expand
</button>
);
}
This shape is easy to mix up with the SDK. Use requestDisplayMode('fullscreen') with the sunpeak hook and app.requestDisplayMode({ mode: 'fullscreen' }) with an App instance.
Two details from the sunpeak 0.20.99 implementation matter here. First, the hook’s function resolves to void, so it does not tell you what the host applied. Second, if the bridge has not connected yet, it logs a warning and returns without sending anything. availableModes is also undefined until the host context arrives, so the ?? false check above keeps the button hidden during that window, which avoids clicks that silently do nothing.
When you need the result object, get the App instance from useApp():
import { useApp } from 'sunpeak';
import type { AppDisplayMode } from 'sunpeak';
export function useModeRequest() {
const app = useApp();
return async (mode: AppDisplayMode) => {
if (!app) return { applied: null, declined: true };
const result = await app.requestDisplayMode({ mode });
return { applied: result.mode, declined: result.mode !== mode };
};
}
To declare the app’s own modes in a React tree you mount yourself, pass them to AppProvider with capabilities={{ availableDisplayModes: ['inline', 'fullscreen'] }}. The resource entry that sunpeak build generates mounts AppProvider with only appInfo, so the app does not send a mode list. Under the spec that means the host has no list to restrict to, but it may still decline undeclared modes, so test the request in each host you target.
Build a Complete Mode Switcher
A production control should block repeat clicks, show only available choices, and tell the user when a request is declined or fails:
import { useState } from 'react';
import { useApp, useDisplayMode, useRequestDisplayMode } from 'sunpeak';
import type { AppDisplayMode } from 'sunpeak';
export function DisplayModeControls() {
const app = useApp();
const displayMode = useDisplayMode();
const { availableModes } = useRequestDisplayMode();
const [pendingMode, setPendingMode] = useState<AppDisplayMode | null>(null);
const [notice, setNotice] = useState<string | null>(null);
const has = (mode: AppDisplayMode) => availableModes?.includes(mode) ?? false;
const request = async (mode: AppDisplayMode) => {
if (!app) return;
setPendingMode(mode);
setNotice(null);
try {
const result = await app.requestDisplayMode({ mode });
if (result.mode !== mode) {
setNotice('The host kept the current view.');
}
} catch {
setNotice('The host could not change the display mode.');
} finally {
setPendingMode(null);
}
};
return (
<fieldset>
<legend>Display options</legend>
{displayMode === 'inline' && has('pip') && (
<button type="button" disabled={pendingMode !== null} onClick={() => request('pip')}>
{pendingMode === 'pip' ? 'Opening...' : 'Pop out'}
</button>
)}
{displayMode !== 'fullscreen' && has('fullscreen') && (
<button
type="button"
disabled={pendingMode !== null}
onClick={() => request('fullscreen')}
>
{pendingMode === 'fullscreen' ? 'Expanding...' : 'Expand'}
</button>
)}
{displayMode !== 'inline' && has('inline') && (
<button type="button" disabled={pendingMode !== null} onClick={() => request('inline')}>
Return to conversation
</button>
)}
{notice && <p role="status">{notice}</p>}
</fieldset>
);
}
The control never stores its own copy of the mode. useDisplayMode() updates from host context, so the buttons follow what the host did, and the result.mode check covers the case a plain try/catch misses: a request that resolves without changing anything.
Do not move focus when the mode changes. The same controls and content should stay keyboard reachable after the host resizes or moves the iframe. The MCP App accessibility testing guide has checks for focus order, labels, touch targets, and zoomed layouts, and WCAG 2.2’s Focus Order criterion explains why a surprise focus jump fails users.
Handle Host-Initiated Mode Changes
Your buttons are not the only way the mode changes. A user can leave fullscreen through the host’s own close control, dismiss a PiP overlay, or rotate a phone, and the host reports each change through ui/notifications/host-context-changed. If the layout depends on “the user clicked Expand,” it breaks the first time the user exits through host chrome.
Branch the layout on useDisplayMode() and keep app state outside that branch:
import { SafeArea, useDisplayMode, useToolData } from 'sunpeak';
interface Report {
title: string;
rows: Array<{ label: string; value: string }>;
}
export function ReportView() {
const displayMode = useDisplayMode();
const { output } = useToolData<unknown, Report>();
if (!output) return null;
const fullscreen = displayMode === 'fullscreen';
return (
<SafeArea
style={{
display: 'grid',
gridTemplateColumns: fullscreen ? 'repeat(2, minmax(0, 1fr))' : '1fr',
gap: '0.75rem',
padding: '1rem',
}}
>
<h1 style={{ gridColumn: '1 / -1' }}>{output.title}</h1>
{output.rows.map((row) => (
<section key={row.label}>
<h2>{row.label}</h2>
<p>{row.value}</p>
</section>
))}
</SafeArea>
);
}
A mode change should resize the experience, not restart it. If a branch unmounts an editor or a map, lift its state up, or persist it with the patterns in the MCP App state persistence guide. When PiP ends because the activity finished, request inline yourself rather than leaving a finished session pinned.
Choose Modes Based on the Task
Fullscreen works when the user has picked a focused task: editing a document or settings, comparing many rows and columns, working on a map, canvas, or timeline, or finishing a long form.
PiP fits content that should stay visible while the conversation goes on:
- A timer or live status.
- Media controls.
- A small reference panel.
- Progress for a long-running job.
- A game round or live session.
Inline has to work on its own. If a host offers only inline, the user should still be able to read the result and start the main action, so swap a wide table for a summary plus detail rows, or split a large form into steps.
Do not hardcode support by host name. Host capabilities differ across web, desktop, mobile, account policy, and release, so read availableDisplayModes at runtime. That is the same feature-detection pattern you use for other optional MCP App APIs.
Test Supported, Missing, and Declined Modes
The sunpeak inspector switches host, display mode, theme, and device size without deploying the MCP server. Its host profiles advertise different mode sets: in sunpeak 0.20.99 the Claude profile lists inline and fullscreen, and the ChatGPT profile lists all three. Switching profiles is a quick way to check that a Pop out button disappears when pip is missing. These are local replicas, so keep a short live check in each real host for the final behavior, as described in the cross-host testing guide.
Start with a layout matrix:
import { test, expect } from 'sunpeak/test';
const displayModes = ['inline', 'pip', 'fullscreen'] as const;
for (const displayMode of displayModes) {
test(`report renders in ${displayMode}`, async ({ inspector }) => {
const result = await inspector.renderTool('show-report', undefined, { displayMode });
const app = result.app();
await expect(app.getByRole('heading', { name: 'Quarterly report' })).toBeVisible();
if (displayMode === 'fullscreen') {
await expect(app.getByRole('button', { name: 'Expand' })).toBeHidden();
}
});
}
Then test the transition itself:
test('expand changes the applied layout', async ({ inspector }) => {
const result = await inspector.renderTool('show-report', undefined, {
displayMode: 'inline',
});
const app = result.app();
await app.getByRole('button', { name: 'Expand' }).click();
await expect(app.getByRole('button', { name: 'Return to conversation' })).toBeVisible();
});
The inspector accepts every request, so cover missing and declined modes in unit tests by mocking the hooks:
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi, test, expect } from 'vitest';
import { DisplayModeControls } from './display-mode-controls';
const requestDisplayMode = vi.fn();
vi.mock('sunpeak', () => ({
useApp: () => ({ requestDisplayMode }),
useDisplayMode: () => 'inline',
useRequestDisplayMode: () => ({ requestDisplayMode: vi.fn(), availableModes: ['inline', 'fullscreen'] }),
}));
test('shows a notice when the host declines fullscreen', async () => {
// Host keeps the app inline and resolves without an error.
requestDisplayMode.mockResolvedValue({ mode: 'inline' });
render(<DisplayModeControls />);
await userEvent.click(screen.getByRole('button', { name: 'Expand' }));
expect(await screen.findByRole('status')).toHaveTextContent('kept the current view');
expect(screen.queryByRole('button', { name: 'Pop out' })).toBeNull();
});
Add cases for availableModes: ['inline'] (no Expand or Pop out button), availableModes: undefined (nothing shown before the host context arrives), a rejected promise, and a rapid double click.
Display Mode Review Checklist
Before shipping a display mode control:
- Declare the modes the app supports during initialization.
- Check the host’s
availableDisplayModesbefore rendering each control. - Call the sunpeak hook with a string, or the SDK with
{ mode }. - Compare
result.modewith the requested mode, and handle rejections. - Render from the host-applied mode, including changes the host makes on its own.
- Keep inline useful when optional modes are missing.
- Keep app state across transitions.
- Test each layout, the missing-mode and declined paths, keyboard use, and narrow widths.
Build and test the same display mode flow across hosts with the sunpeak MCP App framework. Start a project with npx sunpeak new, then use the inspector and Playwright fixtures to cover every transition before you deploy.
Get Started
npx sunpeak newFurther Reading
- ChatGPT App display mode reference - layouts for inline, PiP, and fullscreen
- MCP App capability detection - host features, fallbacks, and tests
- MCP App host context - theme, viewport, and safe areas
- MCP App state persistence - keep state across mode changes
- Cross-host compatibility testing for MCP Apps
- Accessibility testing for MCP App controls and layouts
- MCP App framework - build portable interactive resources
- MCP App inspector - test host states locally
- sunpeak useRequestDisplayMode hook reference
- sunpeak useDisplayMode hook reference
- sunpeak requestDisplayMode SDK reference
- MCP Apps stable specification (2026-01-26) - display mode requirements
- MCP Apps App API reference - requestDisplayMode
Frequently Asked Questions
How do I make an MCP App go fullscreen?
Check that the host lists "fullscreen" in hostContext.availableDisplayModes, then request it from a user action. With the MCP Apps SDK, call await app.requestDisplayMode({ mode: "fullscreen" }) and read result.mode to see what the host applied. In sunpeak React code, call requestDisplayMode("fullscreen") from useRequestDisplayMode() and render from useDisplayMode(), which follows the host-applied mode.
What display modes can an MCP App request?
The MCP Apps specification defines "inline", "fullscreen", and "pip". Inline embeds the app in the conversation, fullscreen gives it the full host window or screen, and pip places it in a floating picture-in-picture overlay. A host can support only a subset, and the app has to keep working when a requested mode is unavailable or declined.
Why did requestDisplayMode resolve but the app stayed inline?
The host declined the request without an error. The MCP Apps spec says a host must return the mode it actually set, and when the requested mode is unavailable it should return the current mode. So a declined request usually resolves with result.mode still equal to "inline". Compare result.mode with the mode you asked for, or read useDisplayMode() in sunpeak, instead of assuming the change happened.
What is the difference between useDisplayMode and useRequestDisplayMode in sunpeak?
useDisplayMode() returns the current host-applied mode and updates when the host sends a context change. useRequestDisplayMode() returns requestDisplayMode(mode), which takes a string such as "fullscreen" and resolves to void, plus availableModes from the host context. Use both: one asks for a change, the other tells you what the host actually did. When you need the result object, call useApp() and use app.requestDisplayMode({ mode }).
Do MCP Apps have to declare which display modes they support?
The spec says a View must declare every mode it supports in appCapabilities.availableDisplayModes during ui/initialize. A host must not switch a View to a mode outside that list when the list is set, and it may decline requests for modes the View did not declare. With the MCP Apps SDK, pass the list as the second argument to new App(). With sunpeak, the AppProvider component accepts a capabilities prop.
Should an MCP App request fullscreen when it mounts?
Usually no. Put display mode changes behind a clear user action such as Expand, Pop out, Done, or Close. Automatic mode changes surprise users and hosts may decline them. Render a useful inline layout first and keep it working if the request is declined or fails.
Can the host change an MCP App display mode without the app asking?
Yes. Users can leave fullscreen or close picture-in-picture through host controls, and the host reports the new mode through ui/notifications/host-context-changed. These updates are partial, so the View merges the new displayMode into its existing context. Drive the layout from the current host context rather than from the last button the user clicked in your app.
How do I test MCP App display mode transitions?
Test four things: the layout in each mode, which controls appear for each advertised mode set, the transition after a user clicks a control, and a declined request that resolves without a change. The sunpeak inspector switches host, display mode, theme, and device size locally, and its Claude and ChatGPT profiles advertise different mode sets. Playwright tests can pass displayMode to inspector.renderTool, and unit tests can mock the hooks for missing modes.