Skip to main content
MCP Apps SDK 
import { App } from "@modelcontextprotocol/ext-apps";

​
Overview

requestDisplayMode asks the host to change how the MCP App View is displayed. The three possible display modes are:
  • "inline" — The default mode. The View is rendered inline within the chat conversation.
  • "fullscreen" — The View expands to fill the host’s available space.
  • "pip" — Picture-in-picture mode. The View floats in a small overlay window.
These values are defined by the McpUiDisplayMode type. See Core Types for the full type definition. The host may not support all display modes. The returned mode reflects what was actually set, which may differ from the requested mode if the host does not support it. Always check the host context’s availableDisplayModes before requesting a mode change, and use the returned value to update your UI state.

​
Signature

async requestDisplayMode(
  params: { mode: McpUiDisplayMode },
  options?: RequestOptions,
): Promise<{ mode: McpUiDisplayMode }>

​
Parameters

​
params
object
required
​
mode
McpUiDisplayMode
required
The desired display mode. One of "inline", "fullscreen", or "pip".
​
options
RequestOptions
Optional request configuration such as timeout or abort signal.

​
Returns

​
result
object
​
mode
McpUiDisplayMode
The display mode actually set by the host. This may differ from the requested mode if the host does not support it.

​
Usage

​
Toggling between inline and fullscreen

const ctx = app.getHostContext();
const newMode = ctx?.displayMode === "inline" ? "fullscreen" : "inline";

if (ctx?.availableDisplayModes?.includes(newMode)) {
  const result = await app.requestDisplayMode({ mode: newMode });
  container.classList.toggle("fullscreen", result.mode === "fullscreen");
}

​
Entering picture-in-picture mode

const ctx = app.getHostContext();

if (ctx?.availableDisplayModes?.includes("pip")) {
  const result = await app.requestDisplayMode({ mode: "pip" });
  if (result.mode === "pip") {
    showMinimalUI();
  }
}

​
Handling unsupported modes gracefully

async function setDisplayMode(desired: McpUiDisplayMode) {
  const ctx = app.getHostContext();

  if (!ctx?.availableDisplayModes?.includes(desired)) {
    console.warn(`Display mode "${desired}" is not available on this host`);
    return;
  }

  const result = await app.requestDisplayMode({ mode: desired });

  if (result.mode !== desired) {
    console.warn(`Requested "${desired}" but host set "${result.mode}"`);
  }

  updateLayout(result.mode);
}

​
Building a mode switcher

const ctx = app.getHostContext();
const modes: McpUiDisplayMode[] = ["inline", "fullscreen", "pip"];

for (const mode of modes) {
  const button = document.createElement("button");
  button.textContent = mode;
  button.disabled = !ctx?.availableDisplayModes?.includes(mode);
  button.addEventListener("click", async () => {
    const result = await app.requestDisplayMode({ mode });
    updateActiveButton(result.mode);
  });
  toolbar.appendChild(button);
}