MCP Apps CSS Variables - Host Theming

MCP Apps SDK

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

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

Overview

Hosts provide CSS custom properties for colors, typography, borders, and more via McpUiHostContext.styles.variables. Use applyHostStyleVariables to set these on the document, then reference them in your CSS with var().

applyHostStyleVariables

Sets each CSS variable from the host as a custom property on the specified element.

Signature

function applyHostStyleVariables(
  styles: McpUiStyles,
  root?: HTMLElement,
): void

styles

McpUiStyles

required

Style variables object from McpUiHostContext.styles.variables.

root

HTMLElement

default:"document.documentElement"

Element to apply styles to.

Usage

// Apply when host context changes
app.onhostcontextchanged = (ctx) => {
  if (ctx.styles?.variables) {
    applyHostStyleVariables(ctx.styles.variables);
  }
};

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

Then use the variables in CSS:

body {
  background-color: var(--color-background-primary);
  color: var(--color-text-primary);
}

.card {
  background-color: var(--color-background-secondary);
  border: 1px solid var(--color-border-primary);
  border-radius: var(--border-radius-lg);
  box-shadow: var(--shadow-sm);
}

Available Variables

All variables are optional — hosts may provide any subset.

Background Colors

Variable	Purpose
`--color-background-primary`	Main background
`--color-background-secondary`	Elevated surfaces
`--color-background-tertiary`	Further elevated surfaces
`--color-background-inverse`	Inverse background
`--color-background-ghost`	Ghost/transparent background
`--color-background-info`	Info state
`--color-background-danger`	Error/danger state
`--color-background-success`	Success state
`--color-background-warning`	Warning state
`--color-background-disabled`	Disabled state

Text Colors

Variable	Purpose
`--color-text-primary`	Main text
`--color-text-secondary`	Secondary text
`--color-text-tertiary`	Tertiary text
`--color-text-inverse`	Text on inverse background
`--color-text-ghost`	Ghost text
`--color-text-info`	Info text
`--color-text-danger`	Error/danger text
`--color-text-success`	Success text
`--color-text-warning`	Warning text
`--color-text-disabled`	Disabled text

Border Colors

Variable	Purpose
`--color-border-primary`	Primary border
`--color-border-secondary`	Secondary border
`--color-border-tertiary`	Tertiary border
`--color-border-inverse`	Inverse border
`--color-border-ghost`	Ghost border
`--color-border-info`	Info border
`--color-border-danger`	Danger border
`--color-border-success`	Success border
`--color-border-warning`	Warning border
`--color-border-disabled`	Disabled border

Ring Colors

Variable	Purpose
`--color-ring-primary`	Primary focus ring
`--color-ring-secondary`	Secondary focus ring
`--color-ring-inverse`	Inverse focus ring
`--color-ring-info`	Info focus ring
`--color-ring-danger`	Danger focus ring
`--color-ring-success`	Success focus ring
`--color-ring-warning`	Warning focus ring

Typography

Variable	Purpose
`--font-sans`	Sans-serif font family
`--font-mono`	Monospace font family
`--font-weight-normal`	Normal weight
`--font-weight-medium`	Medium weight
`--font-weight-semibold`	Semibold weight
`--font-weight-bold`	Bold weight
`--font-text-xs-size` / `--font-text-xs-line-height`	Extra small text
`--font-text-sm-size` / `--font-text-sm-line-height`	Small text
`--font-text-md-size` / `--font-text-md-line-height`	Medium text
`--font-text-lg-size` / `--font-text-lg-line-height`	Large text
`--font-heading-xs-size` / `--font-heading-xs-line-height`	Extra small heading
`--font-heading-sm-size` / `--font-heading-sm-line-height`	Small heading
`--font-heading-md-size` / `--font-heading-md-line-height`	Medium heading
`--font-heading-lg-size` / `--font-heading-lg-line-height`	Large heading
`--font-heading-xl-size` / `--font-heading-xl-line-height`	Extra large heading
`--font-heading-2xl-size` / `--font-heading-2xl-line-height`	2XL heading
`--font-heading-3xl-size` / `--font-heading-3xl-line-height`	3XL heading

Border Radius

Variable	Purpose
`--border-radius-xs`	Extra small radius
`--border-radius-sm`	Small radius
`--border-radius-md`	Medium radius
`--border-radius-lg`	Large radius
`--border-radius-xl`	Extra large radius
`--border-radius-full`	Full/pill radius

Other

Variable	Purpose
`--border-width-regular`	Standard border width
`--shadow-hairline`	Hairline shadow
`--shadow-sm`	Small shadow
`--shadow-md`	Medium shadow
`--shadow-lg`	Large shadow

See also: Theme for light/dark mode detection, and Fonts for host typography.

The sunpeak framework provides useHostContext which auto-applies host styles in React components.

​Overview

​applyHostStyleVariables

​Signature

​Usage

​Available Variables

​Background Colors

​Text Colors

​Border Colors

​Ring Colors

​Typography

​Border Radius

​Other

Overview

applyHostStyleVariables

Signature

Usage

Available Variables

Background Colors

Text Colors

Border Colors

Ring Colors

Typography

Border Radius

Other