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

​
Overview

getHostContext() returns the current host environment context. This includes the theme, styles, locale, time zone, display mode, container dimensions, device capabilities, platform, and safe area insets. The context is first populated during the initialization handshake and automatically updated when the host sends onhostcontextchanged notifications. Returns undefined before connect() completes.

​
Signature

getHostContext(): McpUiHostContext | undefined

​
Returns

​
return
McpUiHostContext | undefined
The current host context, or undefined if the app has not connected yet. See McpUiHostContext for the full type definition.

​
Usage

​
Read the current theme

await app.connect();

const ctx = app.getHostContext();
if (ctx?.theme === "dark") {
  document.body.classList.add("dark-theme");
}

​
Check display mode

const ctx = app.getHostContext();
const isFullscreen = ctx?.displayMode === "fullscreen";

if (isFullscreen) {
  showExpandedLayout();
} else {
  showCompactLayout();
}

​
Use locale for formatting

const ctx = app.getHostContext();
const locale = ctx?.locale ?? "en-US";
const timeZone = ctx?.timeZone ?? "UTC";

const formatted = new Intl.DateTimeFormat(locale, { timeZone }).format(new Date());

​
Adapt to container dimensions

const ctx = app.getHostContext();
const maxWidth = ctx?.containerDimensions?.maxWidth;

if (maxWidth && maxWidth < 400) {
  // Switch to compact layout
}

​
Check device capabilities

const ctx = app.getHostContext();
const hasTouch = ctx?.deviceCapabilities?.touch ?? false;
const hasHover = ctx?.deviceCapabilities?.hover ?? true;

​
Apply safe area insets

const ctx = app.getHostContext();
const insets = ctx?.safeAreaInsets;

if (insets) {
  document.documentElement.style.setProperty("--safe-top", `${insets.top}px`);
  document.documentElement.style.setProperty("--safe-bottom", `${insets.bottom}px`);
}

​
Context Fields

FieldTypeDescription
themeMcpUiTheme"light" or "dark"
stylesMcpUiHostStylesCSS variables and font CSS
displayModeMcpUiDisplayMode"inline", "fullscreen", or "pip"
availableDisplayModesMcpUiDisplayMode[]Modes the host supports
containerDimensionsobjectwidth, maxWidth, height, maxHeight in pixels
localestringBCP 47 locale (e.g., "en-US")
timeZonestringIANA time zone (e.g., "America/New_York")
userAgentstringHost application identifier
platformstring"web", "desktop", or "mobile"
deviceCapabilitiesobjecttouch and hover booleans
safeAreaInsetsobjecttop, right, bottom, left in pixels
toolInfoobjectCurrent tool ID and definition

​
Reactivity

getHostContext() always returns the latest context. When the host sends a context change notification, the App class merges the partial update into its stored context. To react to changes: 
app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) {
    applyDocumentTheme(ctx.theme);
  }
};
The sunpeak framework provides reactive hooks for individual context fields: useHostContext, useTheme, useLocale, useTimeZone, useDisplayMode, useViewport, useDeviceCapabilities, useSafeArea, and usePlatform.