Blend your MCP App with Claude's theme

Claude renders MCP Apps inside a sandboxed iframe, and every frame between your widget and the chat surface already has a transparent background so the conversation can show through. If you leave your own background transparent and style text and borders with the host’s style variables, your app looks like part of the conversation rather than an embedded box. It also follows the user’s light or dark mode automatically. This page is for developers who already have an MCP App rendering in Claude and want it to match the host theme. The snippets assume you have registered a UI resource and created an App instance from @modelcontextprotocol/ext-apps. If you haven’t, start with the SDK Quickstart. To match the host theme, let the host background show through, then apply the host style variables at runtime.

Let the host background show through

Every frame Claude places between your widget and the chat surface is already transparent, so transparency holds as long as your own document doesn’t paint over it. Leave the body background unpainted, declare color-scheme, and request a borderless frame.

Don’t paint a body background

Any opaque background on <html> or <body> hides the chat surface behind it. Explicitly set both to transparent:

html,
body {
  margin: 0;
  background: transparent;
}

Declare `color-scheme` in your document head

Browsers give iframe documents an opaque canvas backdrop, white in light mode and near-black in dark mode, when the iframe’s color-scheme differs from the embedding page. Declaring both schemes opts your document into whichever mode the host is in, so the browser drops the backdrop and makes the CSS light-dark() values in Claude’s tokens resolve correctly:

<meta name="color-scheme" content="light dark" />

Request a borderless frame

Set prefersBorder: false in your UI resource’s _meta.ui object so the host doesn’t wrap your widget in its own bordered card. Claude web’s default is already borderless, but other hosts differ, so being explicit keeps your app portable. Register the resource with registerAppResource:

import {
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

registerAppResource(server, "My Widget", "ui://my-app/widget.html", {}, async () => ({
  contents: [
    {
      uri: "ui://my-app/widget.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: widgetHtml, // the bundled HTML string of your widget; see the SDK Quickstart
      _meta: {
        ui: {
          prefersBorder: false,
          // lets applyHostFonts load Anthropic Sans; see "Allow the host font origin in your CSP"
          csp: { resourceDomains: ["https://assets.claude.ai"] },
        },
      },
    },
  ],
}));

Apply the host style variables

Claude passes a hostContext object to your widget during the connect() handshake. The fields relevant to theming are:

Field	Contents
`theme`	`"light"` or `"dark"`
`styles.variables`	CSS custom properties: `--color-background-`, `--color-text-`, `--color-border-`, `--color-ring-`, `--font-`, `--border-radius-`, `--border-width-*`
`styles.css.fonts`	`@font-face` rules for Anthropic Sans, served from `https://assets.claude.ai`

The Style variables section of the design guidelines lists every variable and its light- and dark-mode value.

Read `hostContext` and listen for changes

The App class exposes the initial context via getHostContext() once connect() resolves, and delivers subsequent updates, such as the user toggling dark mode, through the hostcontextchanged event. Register the listener before you connect so you don’t miss an early update. The SDK provides helpers that do the DOM work for you, and React hooks that wrap them:

applyDocumentTheme(theme) sets <html data-theme> and the root color-scheme, so [data-theme="dark"] selectors and light-dark() values resolve correctly
applyHostStyleVariables(variables) writes every entry in styles.variables onto :root as a CSS custom property
applyHostFonts(fontCss) injects the host’s @font-face rules once
useApp(options) creates and connects the App instance for you in React
useHostStyles(app, hostContext) applies the theme, variables, and fonts and re-applies on hostcontextchanged

Keep the <meta name="color-scheme"> tag in your document head even though applyDocumentTheme also sets color-scheme at runtime. The tag covers the first paint before your script runs and prevents an opaque-backdrop flash. This example applies the theme, variables, and fonts on connect and again on every host context change:

import {
  App,
  applyDocumentTheme,
  applyHostFonts,
  applyHostStyleVariables,
  type McpUiHostContext,
} from "@modelcontextprotocol/ext-apps";

function applyHostContext(ctx: Partial<McpUiHostContext>) {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
}

const app = new App({ name: "my-app", version: "1.0.0" });

// Updates carry only the fields that changed.
app.addEventListener("hostcontextchanged", (changed) => applyHostContext(changed));

await app.connect();
const initial = app.getHostContext();
if (initial) applyHostContext(initial);

import { useApp, useHostStyles } from "@modelcontextprotocol/ext-apps/react";

function Widget() {
  const { app } = useApp({
    appInfo: { name: "my-app", version: "1.0.0" },
    capabilities: {},
  });
  // Applies theme + CSS variables + fonts, and re-applies on host-context-changed.
  useHostStyles(app, app?.getHostContext());
  return <div className="card">…</div>;
}

Reference the variables in your CSS

Once the variables are on :root, reference them directly. Provide fallbacks so the widget is still readable when rendered outside a host:

body {
  font-family: var(--font-sans, system-ui, sans-serif);
  color: var(--color-text-primary, light-dark(#141413, #faf9f5));
}
.card {
  border: var(--border-width-regular, 0.5px) solid var(--color-border-primary);
  border-radius: var(--border-radius-md, 8px);
}

Claude’s token values use CSS light-dark(), so once applyDocumentTheme has set the root color-scheme, every --color-* variable resolves to the right variant without any [data-theme] selectors on your side.

Allow the host font origin in your CSP

For applyHostFonts to load the @font-face files, your resource’s _meta.ui.csp allowlist must include https://assets.claude.ai in resourceDomains, as the registerAppResource snippet shows. resourceDomains also adds the listed origins to script-src and style-src, so keep it to origins you trust to serve executable code. Prefer bundling third-party fonts into your widget rather than allowlisting public CDNs.

Next steps

Style variables: the full variable palette in the design guidelines
Visual design: usage guidance for color, typography, and spacing in the design guidelines
Supersede older widget instances: keep only the newest copy of your widget active in a conversation
SDK API reference: App, McpUiHostContext, and McpUiResourceMeta

Build a plugin

Build an MCP server

Add interactive UI with MCP Apps

Publish to the directory

Let the host background show through

Don’t paint a body background

Declare `color-scheme` in your document head

Request a borderless frame

Apply the host style variables

Read `hostContext` and listen for changes

Reference the variables in your CSS

Allow the host font origin in your CSP

Next steps

​Let the host background show through

​Don’t paint a body background

​Declare color-scheme in your document head

​Request a borderless frame

​Apply the host style variables

​Read hostContext and listen for changes

​Reference the variables in your CSS

​Allow the host font origin in your CSP

​Next steps

Let the host background show through

Don’t paint a body background

Declare `color-scheme` in your document head

Request a borderless frame

Apply the host style variables

Read `hostContext` and listen for changes

Reference the variables in your CSS

Allow the host font origin in your CSP

Next steps