Show your MCP App in the side panel or full screen

• The conversation: the view appears inline
• The side panel: the view appears in a panel next to the conversation, and the conversation stays visible
• Full screen: the view fills the chat area

​

Declare the display modes that a view supports

• No list: Claude treats the view as supporting both modes
• An empty list, or a list without fullscreen: Claude shows no expand button above the view, and doesn’t automatically move the view out of the conversation
• fullscreen without inline: a card appears in the conversation in place of the view.
  • When the user opens the view from the card, it opens in the side panel, or full screen where the panel can’t open.
  • When Claude calls the tool, Claude also tries to open the view in the side panel without a click.

​

Open a view in the side panel without a click

{
  "uri": "ui://example/home",
  "mimeType": "text/html;profile=mcp-app",
  "text": "<!DOCTYPE html>...",
  "_meta": { "ui": { "preferredDisplayMode": "fullscreen" } }
}

• Timing: Claude tries once to move the view, after the view has started and the tool call has returned without an error
• Full screen: a preference doesn’t open the view full screen
• If the view doesn’t move: check why a view with a preference stays in the conversation

​

Request full screen from a click or key press

• With a recent click or key press in the view: Claude opens the view in the side panel, where the mode is also fullscreen
• Without one: Claude refuses the request

import { App } from "@modelcontextprotocol/ext-apps";

const app = new App(
  { name: "example-app", version: "1.0.0" },
  { availableDisplayModes: ["inline", "fullscreen"] }
);
const expandButton = document.querySelector<HTMLButtonElement>("#expand")!;

function layOut() {
  const context = app.getHostContext();
  const size = context?.containerDimensions;
  const canExpand = context?.availableDisplayModes?.includes("fullscreen") ?? false;
  expandButton.hidden = !canExpand || context?.displayMode === "fullscreen";
  document.body.classList.toggle("compact", !!size && "width" in size && size.width < 600);
}

app.addEventListener("hostcontextchanged", layOut);
expandButton.addEventListener("click", async () => {
  const { mode } = await app.requestDisplayMode({ mode: "fullscreen" });
  console.log(`Claude set the display mode to ${mode}`);
});

await app.connect();
layOut();

​

Read the result of requestDisplayMode

​

Lay out a view by the size that Claude reports

• In fullscreen mode: width and height, once Claude has measured the container
• In inline mode: width and maxHeight

• Opening width: about half the width of the chat area
• Minimum width: about 320 pixels

​

Check whether your organization has the side panel

1. Reload Claude on the web, or reload the main Claude Desktop window
2. Open your app in a conversation that has the unified Claude experience, which combines chat and Cowork. If the message box offers a choice of Chat or Cowork, your account doesn’t have it.
3. Look for the expand button, an icon that Claude shows above an inline view. A user clicks it to open the view in the side panel, or full screen where the panel can’t open.

​

Views in a conversation without the side panel

• A fullscreen request: where the side panel isn’t available, the view opens full screen when you request fullscreen, if Claude offers that mode
• fullscreen without inline: in an organization without the side panel, a view that lists fullscreen but not inline appears in the conversation

​

What happens to an open view when Claude calls a tool

• The open view is full screen: the new view can replace it, whichever connector the open view came from.
  • The new view must send ui/notifications/initialized within 15 seconds of when Claude starts to load it. app.connect() sends that notification.
  • The 15 seconds include reading the ui:// resource and loading the view.
  • A view that starts later appears in the conversation, behind the full-screen view.
• The open view is in the side panel: the new view replaces it if both views came from the same connector
• The new view lists fullscreen but not inline: the new view opens in place of anything that the side panel shows

​

Troubleshoot display modes

​

The returned mode differs from the mode that you requested

• A recent click or key press in the view: Claude refuses a fullscreen request with no recent press, such as a request when the view loads or from a timer
• Focus in the view: the view must also have focus. On a button that requests fullscreen, don’t cancel mousedown.
• A mode that Claude offers: the requested mode must be in hostContext.availableDisplayModes. Check the list before you show your own button.
  • Claude lists inline and fullscreen there.
  • It lists only inline where views can’t leave the conversation, such as a chat in its own Claude Desktop window.
• No open prompt, for a return to the conversation: while an approval or sign-in prompt is open, Claude refuses an inline request from the side panel.

​

A view with preferredDisplayMode stays in the conversation

• The side panel shows something else: such as a file, an artifact, or another connector’s view
• The user closed the side panel: they closed it earlier in the same conversation, while it showed a view from your connector. This case no longer applies after the user opens one of your connector’s views with the expand button, or reloads the page.
• The side panel can’t open: for example, the window is narrow, or the side panel isn’t available in the conversation
• The view doesn’t support fullscreen: your availableDisplayModes list doesn’t include the mode

​

Invalid params error when a view starts or requests a mode

​

Next steps

• Let Claude call tools in your MCP App: let Claude change what the user has open in the view
• Let people open your MCP App without asking Claude: list your app in Claude so that people open it themselves