MCP Apps requestDisplayMode - Change Display Mode

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);
}

useRequestDisplayMode — React hook that wraps this method.
Core Types — Full definition of McpUiDisplayMode.
getHostContext() — returns the current display mode and available modes.
Event Handlers — Listen for host-initiated display mode changes.

​Overview

​Signature

​Parameters

​Returns

​Usage

​Toggling between inline and fullscreen

​Entering picture-in-picture mode

​Handling unsupported modes gracefully

​Building a mode switcher

​Related