git:20260507.44b06c0 to git:20260601.da7723a

- ---

- 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

-

- ```typescript

- 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

-

- ```tsx

- 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

-

- ```css

- /* 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` | Layout | Small border radius |

- | `--border-radius-md` | Layout | Medium border radius |

- | `--border-radius-lg` | Layout | Large border radius |

- | `--border-radius-full` | Layout | Full/pill border radius |

-

- ### Hybrid App Styling (MCP + Standalone)

-

- ```css

- /* Works in BOTH modes because of fallback values */

- body {

- margin: 0;

- padding: 0;

- background-color: var(--color-background-primary, #ffffff);

- color: var(--color-text-primary, #1a1a1a);

- font-family: var(--font-sans, system-ui, -apple-system, sans-serif);

- }

-

- /* When host provides variables, they override fallbacks automatically */

- /* When running standalone, fallback values apply */

- ```

-

- ### Fullscreen Mode

-

- ```typescript

- // Configure fullscreen in the tool registration

- registerAppTool(server, {

- name: 'show_dashboard',

- resourceUri: 'app:///dashboard',

- // Request fullscreen display

- displayMode: 'fullscreen',

- async handler(args) { /* ... */ },

- });

- ```

-

- ## Common Pitfalls

-

- 1. **Hardcoding colors/fonts**: Always use CSS variables with fallbacks. Never hardcode `#ffffff` or `Arial` without a variable.

- 2. **Forgetting fallbacks**: Without fallback values, standalone mode will have no styling.

- 3. **Not handling theme changes**: The host can switch themes at any time. Always implement `onhostcontextchanged`.

- 4. **Ignoring safe area insets**: On mobile or certain embedded contexts, content can be obscured without safe area padding.

- 5. **Applying styles after connect()**: Register `onhostcontextchanged` BEFORE `app.connect()`.

-

- ## Verification Checklist

-

- - [ ] All colors use `var(--color-*, fallback)` pattern

- - [ ] All fonts use `var(--font-*, fallback)` pattern

- - [ ] `onhostcontextchanged` handler registered BEFORE `app.connect()`

- - [ ] `applyDocumentTheme` / `applyHostStyleVariables` / `applyHostFonts` called in handler

- - [ ] CSS fallback values are sensible defaults (not broken/empty)

- - [ ] Safe area insets applied to root container

- - [ ] App looks correct in both MCP mode (host variables) and standalone (fallbacks)

- - [ ] Theme switch (light/dark) handled dynamically

-

- ## Task Definition

-

- ```javascript

- const mcpHostStylingTask = defineTask({

- name: 'mcp-host-styling-integration',

- description: 'Integrate MCP App UI with host theming system',

-

- inputs: {

- framework: { type: 'string', required: true },

- hybrid: { type: 'boolean', default: false },

- fullscreen: { type: 'boolean', default: false }

- },

-

- outputs: {

- cssFileCreated: { type: 'boolean' },

- handlerRegistered: { type: 'boolean' },

- artifacts: { type: 'array' }

- },

-

- async run(inputs, taskCtx) {

- return {

- kind: 'skill',

- title: `Integrate host styling (${inputs.framework})`,

- skill: {

- name: 'mcp-host-styling-integration',

- context: {

- framework: inputs.framework,

- hybrid: inputs.hybrid,

- fullscreen: inputs.fullscreen,

- instructions: [

- 'Create CSS with host variable fallbacks',

- 'Implement onhostcontextchanged handler',

- 'Apply theme, style variables, and fonts via SDK helpers',

- 'Add safe area inset padding',

- 'Verify styling in both MCP and standalone modes'

- ]

- }

- },

- io: {

- inputJsonPath: `tasks/${taskCtx.effectId}/input.json`,

- outputJsonPath: `tasks/${taskCtx.effectId}/result.json`

- }

- };

- }

- });

- ```

-

- ## Applicable Processes

-

- - create-mcp-app.js

- - add-app-to-mcp-server.js

- - convert-web-app-to-mcp.js

-

- ## External Dependencies

-

- - `@modelcontextprotocol/ext-apps` (applyDocumentTheme, applyHostStyleVariables, applyHostFonts)

- - `@modelcontextprotocol/ext-apps/react` (useHostStyles, useHostStyleVariables, useHostFonts) -- React only

-

- ## References

-

- - [MCP Apps SDK - Styles](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/styles.ts)

- - [MCP Apps SDK - React Hooks](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useHostStyles.ts)

- - [MCP Apps Patterns](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/patterns.md)

-

- ## Related Skills

-

- - mcp-app-scaffolding

- - mcp-tool-resource-pattern

- - mcp-app-verification

- - single-file-bundling

-

- ## Related Agents

-

- - mcp-ui-developer

- - mcp-app-architect