MCP Apps Core Types - TypeScript Type Reference

MCP Apps SDK

import type {
  McpUiHostContext,
  McpUiHostCapabilities,
  McpUiAppCapabilities,
  McpUiClientCapabilities,
  McpUiTheme,
  McpUiDisplayMode,
  McpUiStyles,
  McpUiStyleVariableKey,
  McpUiHostStyles,
  McpUiHostCss,
  McpUiToolMeta,
  McpUiToolVisibility,
  McpUiResourceMeta,
  McpUiResourceCsp,
  McpUiResourcePermissions,
  McpUiSupportedContentBlockModalities,
} from "@modelcontextprotocol/ext-apps";

McpUiHostContext

Rich context about the host environment, provided during initialization and updated via onhostcontextchanged.

interface McpUiHostContext {
  toolInfo?: {
    id?: RequestId;
    tool: Tool;
  };
  theme?: McpUiTheme;
  styles?: McpUiHostStyles;
  displayMode?: McpUiDisplayMode;
  availableDisplayModes?: McpUiDisplayMode[];
  containerDimensions?: {
    width?: number;     // pixels
    maxWidth?: number;  // pixels
    height?: number;    // pixels
    maxHeight?: number; // pixels
  };
  locale?: string;           // BCP 47 format (e.g., "en-US")
  timeZone?: string;         // IANA format (e.g., "America/New_York")
  userAgent?: string;        // Host application identifier
  platform?: "web" | "desktop" | "mobile";
  deviceCapabilities?: {
    touch?: boolean;
    hover?: boolean;
  };
  safeAreaInsets?: {
    top: number;    // pixels
    right: number;  // pixels
    bottom: number; // pixels
    left: number;   // pixels
  };
}

McpUiHostCapabilities

Capabilities supported by the host, received during initialization.

interface McpUiHostCapabilities {
  experimental?: {};
  openLinks?: {};
  downloadFile?: {};
  serverTools?: { listChanged?: boolean };
  serverResources?: { listChanged?: boolean };
  logging?: {};
  sandbox?: {
    permissions?: McpUiResourcePermissions;
    csp?: McpUiResourceCsp;
  };
  updateModelContext?: McpUiSupportedContentBlockModalities;
  message?: McpUiSupportedContentBlockModalities;
  sampling?: { tools?: {} };
}

Field	Description
`openLinks`	Host supports `openLink()`
`downloadFile`	Host supports `downloadFile()`
`serverTools`	Host can proxy `callServerTool()` to the MCP server
`serverResources`	Host can proxy `readServerResource()` to the MCP server
`logging`	Host accepts `sendLog()` messages
`sandbox`	Permissions and CSP applied by the host
`updateModelContext`	Host accepts `updateModelContext()`
`message`	Host accepts `sendMessage()`
`sampling`	Host supports `createSamplingMessage()` for LLM completions. `sampling.tools` indicates tool-augmented sampling support.

McpUiAppCapabilities

Capabilities provided by the View, sent during initialization.

interface McpUiAppCapabilities {
  experimental?: {};
  tools?: { listChanged?: boolean };
  availableDisplayModes?: McpUiDisplayMode[];
}

Field	Description
`tools`	App exposes tools that the host can call via `oncalltool`
`availableDisplayModes`	Display modes the app supports

McpUiClientCapabilities

Advertised by hosts to servers via the MCP extensions field. Used with getUiCapability().

interface McpUiClientCapabilities {
  mimeTypes?: string[];  // Must include "text/html;profile=mcp-app"
}

McpUiTheme

type McpUiTheme = "light" | "dark";

The sunpeak framework also exports a short alias: Theme (equivalent to McpUiTheme).

McpUiDisplayMode

type McpUiDisplayMode = "inline" | "fullscreen" | "pip";

The sunpeak framework also exports a short alias: DisplayMode (equivalent to McpUiDisplayMode).

McpUiHostStyles

interface McpUiHostStyles {
  variables?: McpUiStyles;
  css?: McpUiHostCss;
}

McpUiHostCss

interface McpUiHostCss {
  fonts?: string;  // @font-face rules or @import statements
}

McpUiStyles

A record mapping CSS variable names to string values. All keys are optional.

type McpUiStyles = Record<McpUiStyleVariableKey, string | undefined>;

See CSS Variables for the full list of variable keys.

McpUiToolMeta

UI metadata for tools, set in _meta.ui of tool configuration.

interface McpUiToolMeta {
  resourceUri?: string;
  visibility?: McpUiToolVisibility[];  // Default: ["model", "app"]
}

McpUiToolVisibility

type McpUiToolVisibility = "model" | "app";

McpUiResourceMeta

UI metadata for resources, set in _meta.ui of resource content items.

interface McpUiResourceMeta {
  csp?: McpUiResourceCsp;
  permissions?: McpUiResourcePermissions;
  domain?: string;
  prefersBorder?: boolean;
}

McpUiResourceCsp

Content Security Policy configuration.

interface McpUiResourceCsp {
  connectDomains?: string[];     // fetch/XHR/WebSocket origins
  resourceDomains?: string[];    // img/script/style/font/media origins
  frameDomains?: string[];       // Nested iframe origins
  baseUriDomains?: string[];     // Allowed base URIs
}

McpUiResourcePermissions

Browser capabilities requested by the resource.

interface McpUiResourcePermissions {
  camera?: {};
  microphone?: {};
  geolocation?: {};
  clipboardWrite?: {};
}

McpUiSupportedContentBlockModalities

Content block types supported by the host for sendMessage and updateModelContext.

interface McpUiSupportedContentBlockModalities {
  text?: {};
  image?: {};
  audio?: {};
  resource?: {};
  resourceLink?: {};
  structuredContent?: {};
}

The sunpeak framework provides convenience hooks for accessing these types reactively: useHostContext, useHostInfo, and useTheme.

​McpUiHostContext

​McpUiHostCapabilities

​McpUiAppCapabilities

​McpUiClientCapabilities

​McpUiTheme

​McpUiDisplayMode

​McpUiHostStyles

​McpUiHostCss

​McpUiStyles

​McpUiToolMeta

​McpUiToolVisibility

​McpUiResourceMeta

​McpUiResourceCsp

​McpUiResourcePermissions

​McpUiSupportedContentBlockModalities