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 |
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)
/* 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
// Configure fullscreen in the tool registration
registerAppTool(server, {
name: 'show_dashboard',
resourceUri: 'app:///dashboard',
// Request fullscreen display
displayMode: 'fullscreen',
async handler(args) { /* ... */ },
});
Common Pitfalls
- Hardcoding colors/fonts: Always use CSS variables with fallbacks. Never hardcode
#ffffff or Arial without a variable.
- Forgetting fallbacks: Without fallback values, standalone mode will have no styling.
- Not handling theme changes: The host can switch themes at any time. Always implement
onhostcontextchanged.
- Ignoring safe area insets: On mobile or certain embedded contexts, content can be obscured without safe area padding.
- Applying styles after connect(): Register
onhostcontextchanged BEFORE app.connect().
Verification Checklist
Task Definition
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
Related Skills
- mcp-app-scaffolding
- mcp-tool-resource-pattern
- mcp-app-verification
- single-file-bundling
Related Agents
- mcp-ui-developer
- mcp-app-architect
1---
2name: mcp-host-styling-integration
3description: Integrates MCP App UI with host theming system. Applies host CSS variables, handles onhostcontextchanged, safe area insets, display mode detection, and fullscreen configuration.
4allowed-tools: Read, Write, Edit
5graph:
6 domains: [domain:software-engineering]
7 specializations: [specialization:ai-agents-conversational]
8 skillAreas: [skill-area:mcp-server-implementation, skill-area:mcp-resource-design]
9 roles: [role:backend-engineer, role:fullstack-engineer]
10 workflows: [workflow:feature-development]
11
12metadata:
13 source: https://skillmd.com/skills/a5c-ai/mcp-host-styling-integration
14---
15
16# mcp-host-styling-integration
17
18Integrate 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.
19
20## Overview
21
22MCP 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:
23- **CSS variables** (`--color-*`, `--font-*`, `--border-radius-*`) injected by the host
24- **SDK helpers** (`applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts`) to apply them
25- **React hooks** (`useHostStyles`, `useHostStyleVariables`, `useHostFonts`) for React apps
26- **`onhostcontextchanged` event** fired when theme changes (e.g., dark mode toggle)
27
28The 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).
29
30## Capabilities
31
32### Host CSS Variable Integration
33- Apply all host CSS variables with sensible fallback values
34- Support color variables: `--color-background-primary`, `--color-background-secondary`, `--color-text-primary`, `--color-text-secondary`, `--color-border-primary`
35- Support font variables: `--font-sans`, `--font-mono`, `--font-text-base-size`, `--font-text-sm-size`
36- Support layout variables: `--border-radius-sm`, `--border-radius-md`, `--border-radius-lg`
37
38### onhostcontextchanged Handler
39- Listen for theme changes from the host
40- Reapply styling when theme changes (e.g., light to dark mode)
41- Access host context: theme, display mode, safe area insets
42
43### Safe Area Insets
44- Apply safe area padding for mobile or embedded contexts
45- Handle `env(safe-area-inset-top)`, `env(safe-area-inset-bottom)`, etc.
46
47### Display Mode Detection
48- Detect embedded vs fullscreen mode
49- Adapt layout based on available space
50- Configure fullscreen mode via tool metadata
51
52### SDK Helper Functions
53- `applyDocumentTheme(theme)` -- sets document-level theme class
54- `applyHostStyleVariables(context)` -- applies all CSS variables from host
55- `applyHostFonts(context)` -- loads and applies host fonts
56
57### React Hook Integration
58- `useHostStyles()` -- combined hook applying theme, variables, and fonts
59- `useHostStyleVariables()` -- CSS variables only
60- `useHostFonts()` -- font loading only
61
62## Usage
63
64### Vanilla JS: Full Host Styling
65
66```typescript
67import {
68 App,
69 PostMessageTransport,
70 applyDocumentTheme,
71 applyHostStyleVariables,
72 applyHostFonts,
73} from '@modelcontextprotocol/ext-apps';
74
75const app = new App({ transport: new PostMessageTransport() });
76
77// Register handler BEFORE connect()
78app.onhostcontextchanged = (params) => {
79 const ctx = params.context;
80
81 // Apply theme (light/dark)
82 if (ctx.theme) {
83 applyDocumentTheme(ctx.theme);
84 }
85
86 // Apply CSS variables
87 applyHostStyleVariables(ctx);
88
89 // Load and apply fonts
90 applyHostFonts(ctx);
91};
92
93// THEN connect
94await app.connect();
95```
96
97### React: useHostStyles Hook
98
99```tsx
100import { useApp, useHostStyles } from '@modelcontextprotocol/ext-apps/react';
101
102function MyApp() {
103 const app = useApp();
104 useHostStyles(); // Handles all theme/variable/font application
105
106 return (
107 <div className="app-container">
108 <h1>My MCP App</h1>
109 </div>
110 );
111}
112```
113
114### CSS with Fallback Values
115
116```css
117/* Always use fallbacks so app works standalone too */
118.app-container {
119 background-color: var(--color-background-primary, #ffffff);
120 color: var(--color-text-primary, #1a1a1a);
121 font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
122 font-size: var(--font-text-base-size, 14px);
123 border-radius: var(--border-radius-md, 8px);
124}
125
126.card {
127 background-color: var(--color-background-secondary, #f5f5f5);
128 border: 1px solid var(--color-border-primary, #e0e0e0);
129 border-radius: var(--border-radius-sm, 4px);
130 padding: 16px;
131}
132
133.label {
134 color: var(--color-text-secondary, #666666);
135 font-size: var(--font-text-sm-size, 12px);
136}
137
138.code {
139 font-family: var(--font-mono, 'Courier New', monospace);
140}
141
142/* Safe area insets for mobile/embedded contexts */
143.app-root {
144 padding-top: env(safe-area-inset-top, 0px);
145 padding-bottom: env(safe-area-inset-bottom, 0px);
146 padding-left: env(safe-area-inset-left, 0px);
147 padding-right: env(safe-area-inset-right, 0px);
148}
149```
150
151### Available Host CSS Variables
152
153| Variable | Category | Description |
154|----------|----------|-------------|
155| `--color-background-primary` | Color | Main background |
156| `--color-background-secondary` | Color | Card/section background |
157| `--color-background-tertiary` | Color | Nested/subtle background |
158| `--color-text-primary` | Color | Main text |
159| `--color-text-secondary` | Color | Secondary/muted text |
160| `--color-text-tertiary` | Color | Subtle/hint text |
161| `--color-border-primary` | Color | Main borders |
162| `--color-border-secondary` | Color | Subtle borders |
163| `--color-accent` | Color | Interactive elements |
164| `--color-error` | Color | Error states |
165| `--color-success` | Color | Success states |
166| `--color-warning` | Color | Warning states |
167| `--font-sans` | Font | Sans-serif font family |
168| `--font-mono` | Font | Monospace font family |
169| `--font-text-xs-size` | Font | Extra small text size |
170| `--font-text-sm-size` | Font | Small text size |
171| `--font-text-base-size` | Font | Base text size |
172| `--font-text-lg-size` | Font | Large text size |
173| `--font-text-xl-size` | Font | Extra large text size |
174| `--border-radius-sm` | Layout | Small border radius |
175| `--border-radius-md` | Layout | Medium border radius |
176| `--border-radius-lg` | Layout | Large border radius |
177| `--border-radius-full` | Layout | Full/pill border radius |
178
179### Hybrid App Styling (MCP + Standalone)
180
181```css
182/* Works in BOTH modes because of fallback values */
183body {
184 margin: 0;
185 padding: 0;
186 background-color: var(--color-background-primary, #ffffff);
187 color: var(--color-text-primary, #1a1a1a);
188 font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
189}
190
191/* When host provides variables, they override fallbacks automatically */
192/* When running standalone, fallback values apply */
193```
194
195### Fullscreen Mode
196
197```typescript
198// Configure fullscreen in the tool registration
199registerAppTool(server, {
200 name: 'show_dashboard',
201 resourceUri: 'app:///dashboard',
202 // Request fullscreen display
203 displayMode: 'fullscreen',
204 async handler(args) { /* ... */ },
205});
206```
207
208## Common Pitfalls
209
2101. **Hardcoding colors/fonts**: Always use CSS variables with fallbacks. Never hardcode `#ffffff` or `Arial` without a variable.
2112. **Forgetting fallbacks**: Without fallback values, standalone mode will have no styling.
2123. **Not handling theme changes**: The host can switch themes at any time. Always implement `onhostcontextchanged`.
2134. **Ignoring safe area insets**: On mobile or certain embedded contexts, content can be obscured without safe area padding.
2145. **Applying styles after connect()**: Register `onhostcontextchanged` BEFORE `app.connect()`.
215
216## Verification Checklist
217
218- [ ] All colors use `var(--color-*, fallback)` pattern
219- [ ] All fonts use `var(--font-*, fallback)` pattern
220- [ ] `onhostcontextchanged` handler registered BEFORE `app.connect()`
221- [ ] `applyDocumentTheme` / `applyHostStyleVariables` / `applyHostFonts` called in handler
222- [ ] CSS fallback values are sensible defaults (not broken/empty)
223- [ ] Safe area insets applied to root container
224- [ ] App looks correct in both MCP mode (host variables) and standalone (fallbacks)
225- [ ] Theme switch (light/dark) handled dynamically
226
227## Task Definition
228
229```javascript
230const mcpHostStylingTask = defineTask({
231 name: 'mcp-host-styling-integration',
232 description: 'Integrate MCP App UI with host theming system',
233
234 inputs: {
235 framework: { type: 'string', required: true },
236 hybrid: { type: 'boolean', default: false },
237 fullscreen: { type: 'boolean', default: false }
238 },
239
240 outputs: {
241 cssFileCreated: { type: 'boolean' },
242 handlerRegistered: { type: 'boolean' },
243 artifacts: { type: 'array' }
244 },
245
246 async run(inputs, taskCtx) {
247 return {
248 kind: 'skill',
249 title: `Integrate host styling (${inputs.framework})`,
250 skill: {
251 name: 'mcp-host-styling-integration',
252 context: {
253 framework: inputs.framework,
254 hybrid: inputs.hybrid,
255 fullscreen: inputs.fullscreen,
256 instructions: [
257 'Create CSS with host variable fallbacks',
258 'Implement onhostcontextchanged handler',
259 'Apply theme, style variables, and fonts via SDK helpers',
260 'Add safe area inset padding',
261 'Verify styling in both MCP and standalone modes'
262 ]
263 }
264 },
265 io: {
266 inputJsonPath: `tasks/${taskCtx.effectId}/input.json`,
267 outputJsonPath: `tasks/${taskCtx.effectId}/result.json`
268 }
269 };
270 }
271});
272```
273
274## Applicable Processes
275
276- create-mcp-app.js
277- add-app-to-mcp-server.js
278- convert-web-app-to-mcp.js
279
280## External Dependencies
281
282- `@modelcontextprotocol/ext-apps` (applyDocumentTheme, applyHostStyleVariables, applyHostFonts)
283- `@modelcontextprotocol/ext-apps/react` (useHostStyles, useHostStyleVariables, useHostFonts) -- React only
284
285## References
286
287- [MCP Apps SDK - Styles](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/styles.ts)
288- [MCP Apps SDK - React Hooks](https://github.com/modelcontextprotocol/ext-apps/blob/main/src/react/useHostStyles.ts)
289- [MCP Apps Patterns](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/patterns.md)
290
291## Related Skills
292
293- mcp-app-scaffolding
294- mcp-tool-resource-pattern
295- mcp-app-verification
296- single-file-bundling
297
298## Related Agents
299
300- mcp-ui-developer
301- mcp-app-architect