MCP Apps getHostContext - Host Environment State

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

Field	Type	Description
`theme`	`McpUiTheme`	`"light"` or `"dark"`
`styles`	`McpUiHostStyles`	CSS variables and font CSS
`displayMode`	`McpUiDisplayMode`	`"inline"`, `"fullscreen"`, or `"pip"`
`availableDisplayModes`	`McpUiDisplayMode[]`	Modes the host supports
`containerDimensions`	`object`	`width`, `maxWidth`, `height`, `maxHeight` in pixels
`locale`	`string`	BCP 47 locale (e.g., `"en-US"`)
`timeZone`	`string`	IANA time zone (e.g., `"America/New_York"`)
`userAgent`	`string`	Host application identifier
`platform`	`string`	`"web"`, `"desktop"`, or `"mobile"`
`deviceCapabilities`	`object`	`touch` and `hover` booleans
`safeAreaInsets`	`object`	`top`, `right`, `bottom`, `left` in pixels
`toolInfo`	`object`	Current 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:

Vanilla JS — Register an onhostcontextchanged handler
React — Use the sunpeak useHostContext hook for reactive updates

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) {
    applyDocumentTheme(ctx.theme);
  }
};

McpUiHostContext — Full type definition
onhostcontextchanged — Event handler for context updates
getHostCapabilities() — What the host supports
getHostVersion() — Host identification
Accessors overview — All App accessor methods

The sunpeak framework provides reactive hooks for individual context fields: useHostContext, useTheme, useLocale, useTimeZone, useDisplayMode, useViewport, useDeviceCapabilities, useSafeArea, and usePlatform.

​Overview

​Signature

​Returns

​Usage

​Read the current theme

​Check display mode

​Use locale for formatting

​Adapt to container dimensions

​Check device capabilities

​Apply safe area insets

​Context Fields

​Reactivity

​Related