/mcp-host-styling-integration

name: mcp-host-styling-integration
description: Integrates MCP App UI with host theming system. Applies host CSS variables, handles onhostcontextchanged, safe area insets, display mode detection, and fullscreen configuration.
allowed-tools: Read, Write, Edit
graph:
  domains: [domain:software-engineering]
  specializations: [specialization:ai-agents-conversational]
  skillAreas: [skill-area:mcp-server-implementation, skill-area:mcp-resource-design]
  roles: [role:backend-engineer, role:fullstack-engineer]
  workflows: [workflow:feature-development]

mcp-host-styling-integration

Integrate MCP App UIs with the host application's theming system so apps look native in Claude Desktop, ChatGPT, VS Code, Goose, Postman, and other MCP-enabled hosts.

Overview

MCP Apps render in sandboxed iframes inside host applications. Each host has its own visual theme (colors, fonts, border radii, spacing). The MCP Apps SDK provides:

• **CSS variables** (`--color-*`, `--font-*`, `--border-radius-*`) injected by the host
• **SDK helpers** (`applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts`) to apply them
• **React hooks** (`useHostStyles`, `useHostStyleVariables`, `useHostFonts`) for React apps
• **`onhostcontextchanged` event** fired when theme changes (e.g., dark mode toggle)

The key principle is: always use CSS variable fallbacks so the app looks correct both as an MCP App (host provides variables) and standalone (fallback values apply).

Capabilities

Host CSS Variable Integration

• Apply all host CSS variables with sensible fallback values
• Support color variables: `--color-background-primary`, `--color-background-secondary`, `--color-text-primary`, `--color-text-secondary`, `--color-border-primary`
• Support font variables: `--font-sans`, `--font-mono`, `--font-text-base-size`, `--font-text-sm-size`
• Support layout variables: `--border-radius-sm`, `--border-radius-md`, `--border-radius-lg`

onhostcontextchanged Handler

• Listen for theme changes from the host
• Reapply styling when theme changes (e.g., light to dark mode)
• Access host context: theme, display mode, safe area insets

Safe Area Insets

• Apply safe area padding for mobile or embedded contexts
• Handle `env(safe-area-inset-top)`, `env(safe-area-inset-bottom)`, etc.

Display Mode Detection

• Detect embedded vs fullscreen mode
• Adapt layout based on available space
• Configure fullscreen mode via tool metadata

SDK Helper Functions

• `applyDocumentTheme(theme)` -- sets document-level theme class
• `applyHostStyleVariables(context)` -- applies all CSS variables from host
• `applyHostFonts(context)` -- loads and applies host fonts

React Hook Integration

• `useHostStyles()` -- combined hook applying theme, variables, and fonts
• `useHostStyleVariables()` -- CSS variables only
• `useHostFonts()` -- font loading only

Usage

Vanilla JS: Full Host Styling

import {
  App,
  PostMessageTransport,
  applyDocumentTheme,
  applyHostStyleVariables,
  applyHostFonts,
} from '@modelcontextprotocol/ext-apps';

const app = new App({ transport: new PostMessageTransport() });

// Register handler BEFORE connect()
app.onhostcontextchanged = (params) => {
  const ctx = params.context;

  // Apply theme (light/dark)
  if (ctx.theme) {
    applyDocumentTheme(ctx.theme);
  }

  // Apply CSS variables
  applyHostStyleVariables(ctx);

  // Load and apply fonts
  applyHostFonts(ctx);
};

// THEN connect
await app.connect();

React: useHostStyles Hook

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

function MyApp() {
  const app = useApp();
  useHostStyles();  // Handles all theme/variable/font application

  return (
    <div className="app-container">
      <h1>My MCP App</h1>
    </div>
  );
}

CSS with Fallback Values

/* Always use fallbacks so app works standalone too */
.app-container {
  background-color: var(--color-background-primary, #ffffff);
  color: var(--color-text-primary, #1a1a1a);
  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
  font-size: var(--font-text-base-size, 14px);
  border-radius: var(--border-radius-md, 8px);
}

.card {
  background-color: var(--color-background-secondary, #f5f5f5);
  border: 1px solid var(--color-border-primary, #e0e0e0);
  border-radius: var(--border-radius-sm, 4px);
  padding: 16px;
}

.label {
  color: var(--color-text-secondary, #666666);
  font-size: var(--font-text-sm-size, 12px);
}

.code {
  font-family: var(--font-mono, 'Courier New', monospace);
}

/* Safe area insets for mobile/embedded contexts */
.app-root {
  padding-top: env(safe-area-inset-top, 0px);
  padding-bottom: env(safe-area-inset-bottom, 0px);
  padding-left: env(safe-area-inset-left, 0px);
  padding-right: env(safe-area-inset-right, 0px);
}

Available Host CSS Variables

| Variable | Category | Description | |----------|----------|-------------| | `--color-background-primary` | Color | Main background | | `--color-background-secondary` | Color | Card/section background | | `--color-background-tertiary` | Color | Nested/subtle background | | `--color-text-primary` | Color | Main text | | `--color-text-secondary` | Color | Secondary/muted text | | `--color-text-tertiary` | Color | Subtle/hint text | | `--color-border-primary` | Color | Main borders | | `--color-border-secondary` | Color | Subtle borders | | `--color-accent` | Color | Interactive elements | | `--color-error` | Color | Error states | | `--color-success` | Color | Success states | | `--color-warning` | Color | Warning states | | `--font-sans` | Font | Sans-serif font family | | `--font-mono` | Font | Monospace font family | | `--font-text-xs-size` | Font | Extra small text size | | `--font-text-sm-size` | Font | Small text size | | `--font-text-base-size` | Font | Base text size | | `--font-text-lg-size` | Font | Large text size | | `--font-text-xl-size` | Font | Extra large text size | | `--border-radius-sm` |