MCP Apps Theme - Light and Dark Mode for AI Chat UIs

MCP Apps SDK

import { applyDocumentTheme, getDocumentTheme } from "@modelcontextprotocol/ext-apps";

In React components, useHostStyles applies theme, CSS variables, and fonts automatically. The functions below are useful for non-React usage or custom control.

Overview

Hosts provide a theme preference ("light" or "dark") via host context. The SDK provides functions to apply this theme to the document and read the current theme state.

applyDocumentTheme

Sets the data-theme attribute and color-scheme CSS property on document.documentElement. This enables:

CSS selectors like [data-theme="dark"]
The CSS light-dark() function
Native elements (scrollbars, form controls) respecting the theme

Signature

function applyDocumentTheme(theme: McpUiTheme): void

Usage

// Apply when host context changes
app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) {
    applyDocumentTheme(ctx.theme);
  }
};

// Apply initial theme after connecting
await app.connect();
const ctx = app.getHostContext();
if (ctx?.theme) {
  applyDocumentTheme(ctx.theme);
}

CSS Selectors

After calling applyDocumentTheme, use these patterns in your CSS:

/* Attribute selector */
[data-theme="dark"] {
  --bg-color: #1a1a1a;
}
[data-theme="light"] {
  --bg-color: #ffffff;
}

/* CSS light-dark() function (requires color-scheme) */
body {
  background: light-dark(#ffffff, #1a1a1a);
  color: light-dark(#000000, #ffffff);
}

getDocumentTheme

Reads the current theme from document.documentElement. Checks the data-theme attribute first, then falls back to the dark class for Tailwind CSS compatibility.

Signature

function getDocumentTheme(): McpUiTheme

Usage

const theme = getDocumentTheme();
document.body.classList.toggle("dark", theme === "dark");

McpUiTheme

type McpUiTheme = "light" | "dark";

See also: CSS Variables for host-provided color tokens, and Fonts for host typography.

The sunpeak framework provides useTheme for reactive theme access in React components.

​Overview

​applyDocumentTheme

​Signature

​Usage

​CSS Selectors

​getDocumentTheme

​Signature

​Usage

​McpUiTheme

Overview

applyDocumentTheme

Signature

Usage

CSS Selectors

getDocumentTheme

Signature

Usage

McpUiTheme