[MCP Apps] Add `styles` prop to host context #127

martinalong · 2025-12-10T23:31:05Z

Summary

Adds a way for hosts to pass a basic set of theming variables to MCP Apps, primarily around colors and fonts
- The set of variable names to pass is preset/standardized
Also adds some utilities for plugging these styles in as CSS variables, and setting/getting theme
Updates the customer-segmentation-server to use these styles

Some choices we made in landing on this architecture / our thought process:

The goal is to just make the app relatively cohesive with the host, not to make it look native to the host. The latter simply isn't realistic because there are some things that simply can't be UI paradigms
We chose to not provide a UI component set (buttons, modals, inputs, etc), since no single component set would work for all hosts
The number of variables is intentionally limited, since hosts that use this would be recommended to supply all variables
After some debate, we settled on not including spacing variables, because we figured that many designs would simply break (or look bad) if spacing varied too much from how they'd originally been designed

What if a host doesn't provide styles?

Apps should always provide their own defaults for each style variable that they rely on.
- This is to account for hosts that don't pass the style object
- And to allow for future additions to the spec that some hosts might not have updated to support yet

Request for input

Making a standard for styling that'll work with many hosts is a tricky thing to get right, so this definitely isn't final, and we welcome discussion on it!

Some things that we are still thinking about and would love input on:

How hosts can specify fonts that require importing (e.g. google fonts or entirely custom fonts)
Are there any variables we're missing that should be added?
- We already have plans to add a few more heading levels, some more color styles, and box shadow styles

pkg-pr-new · 2025-12-10T23:31:55Z

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@127

commit: 8f591b6

ochafik · 2025-12-11T14:53:18Z

src/spec.types.ts

Maybe merge the spec change into this one? Spec types are really part of the spec, I think having it all atomically together is best.

Agreed, I added some comments on the spec's PR (since they're more high-level) - and it would be easier to have the SDK and the spec at the same PR.

liady · 2025-12-11T15:03:19Z

Nice!
Commented on the spec PR on some of the questions - #130 (comment) .
I think we should define the level of design consistency we're aiming for across apps - this might require some more semantic variables in addition to the atomic ones.

martinalong · 2025-12-14T20:38:49Z

@liady we added more tokens and some semantic styles, but we didn't think it was realistic to be able to capture the full range of component <> variable sets (e.g. button borderradius, button primary/secondary/tertiary color, modal border radius, modal padding, etc) because there's just an endless number of components. The goal is really just to get apps to not clash with the host, not to make it look native to the host, so we think this set should be sufficient for now

Also, we made it styles.variables instead of just styles!

martinalong · 2025-12-14T21:37:05Z

examples/basic-host/index.html

  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="color-scheme" content="light dark">


I made this change to all the examples so that they can properly have a transparent background. Without it, iframe sets a default black/white background

martinalong · 2025-12-14T21:37:34Z

examples/customer-segmentation-server/src/mcp-app.css

-    --color-smb: #10b981;
-    --color-startup: #818cf8;
-  }
+  color-scheme: light dark;


Changes in this file are me updating this one example to use the host context styles (with its original styles as fallbacks)

martinalong · 2025-12-14T21:38:18Z

examples/customer-segmentation-server/src/mcp-app.ts

+let colorResolver: HTMLDivElement | null = null;
+
+// Resolve a CSS color value (handles light-dark() function)
+function resolveColor(cssValue: string, fallback: string): string {


This is necessary for this particular example b/c chartJS doesn't play nicely with light-dark by default

ochafik

Quick high-level comments, will review more thorougly shortly:

Can we fence under a host capability?
Can you build a table of equivalence mapping between these variables and OpenAI Apps SDK variables? (add a STYLES.md) Hope to avoid confusion for users targetting both MCP Apps and OAI Apps SDK.

antonpk1

awesome contribution!

I think it's fine to not have capability negotiation here - this is just an optional field
also we can evolve set of variables over time in follow-up commits

martinalong · 2025-12-15T19:40:32Z

@ochafik if it's something we can follow up on i'd strongly prefer to do that. This PR needs to go out roughly the same time as another one, and that's a bit tough to coordinate

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Add styles field to HostContext interface with reference to Theming section - Add Theming section documenting 36 standardized CSS variables - Document Host/App behavior for theming including light-dark() usage - Add Design Decision #4 explaining CSS variables approach - Include JSON example showing light-dark() pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Prevents iframe from automatically applying a default background color. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Updated screenshots to reflect UI changes from styles addition. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

liady · 2025-12-15T19:48:08Z

@ochafik it can be nice if the MCP Apps React UI SDK would somehow already have the ChatGPT Apps <> MCP Apps style variable mapping, perhaps as a .css file that can be imported by the app authors. This could be as simple as:

/* 
This maps tokens from ChatGPT Apps design system to MCP Apps design system - where the latter are missing.
--mcp-apps-variable-name: var(--chatgpt-apps-variable-name);
*/

--color-background-primary: var(--color-background-primary-solid);
--color-background-secondary: var(--color-background-secondary-solid);
--color-background-tertiary: var(--color-surface-tertiary);
--color-background-inverse: var(--color-text-inverse);
--color-background-ghost: transparent;

--color-background-info: var(--color-background-info-solid);
--color-background-danger: var(--color-background-danger-solid);
--color-background-success: var(--color-background-success-solid);
--color-background-warning: var(--color-background-warning-solid);
--color-border-primary: var(--color-border-primary-outline);
--color-border-secondary: var(--color-border-secondary-outline);
--color-border-tertiary: var(--color-border-subtle);
--color-border-inverse: var(--color-text-inverse);
--color-border-ghost: transparent;

--color-border-info: var(--color-border-info-outline);
--color-border-danger: var(--color-border-danger-outline);
--color-border-success: var(--color-border-success-outline);
--color-border-warning: var(--color-border-warning-outline);
--color-ring-inverse: var(--color-text-inverse);
--border-radius-xs: var(--radius-xs);
--border-radius-sm: var(--radius-sm);
--border-radius-md: var(--radius-md);
--border-radius-lg: var(--radius-lg);
--border-radius-xl: var(--radius-xl);
--border-radius-full: var(--radius-full);
--border-width-regular: 1px;
--shadow-sm: var(--shadow-100);
--shadow-md: var(--shadow-200);
--shadow-lg: var(--shadow-300);

This maps the ChatGPT Apps variables to matching MCP Apps variables (the rest of the list exists in both systems). This way app authors would be able to write MCP Apps applications and only use this compatibility layer when targeting ChatGPT Apps.
What do you think?

Will address in followup

martinalong changed the title ~~[MCP Apps] Add styles prop to host context~~ [MCP Apps] Add styles prop to host context Dec 10, 2025

martinalong requested review from antonpk1 and ochafik December 10, 2025 23:55

martinalong mentioned this pull request Dec 11, 2025

SEP: Theming #123

Open

antonpk1 mentioned this pull request Dec 11, 2025

docs: add styles to MCP Apps specification #130

Merged

ochafik reviewed Dec 11, 2025

View reviewed changes

ochafik requested a review from alexi-openai December 11, 2025 17:02

martinalong force-pushed the martinalong/mcp-apps/add-styles branch from d07eb1f to 0c7bcd0 Compare December 14, 2025 20:33

martinalong commented Dec 14, 2025

View reviewed changes

martinalong force-pushed the martinalong/mcp-apps/add-styles branch from 6f490f5 to 7166f75 Compare December 14, 2025 21:41

ochafik previously requested changes Dec 15, 2025

View reviewed changes

antonpk1 previously approved these changes Dec 15, 2025

View reviewed changes

martinalong and others added 12 commits December 15, 2025 11:42

Add styles prop to host context

9e97bf3

Add utility for using styles

aa89688

Add utility to set + read theme

a8b3bf0

Regenerate schemas after npm install

f276ec6

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Suggested edits

aaedd85

Make properties optional

db28726

Add color-scheme meta tag to all example apps

3578186

Prevents iframe from automatically applying a default background color. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Updates example to use theme colors and adds border radius

2fa243a

Make it styles.variables instead of styles

445a583

Finalized variable set

aa79cb7

Fix markdown typo

5db8076

martinalong and others added 3 commits December 15, 2025 11:42

Update generated schemas with stricter datetime pattern

2f8d1ec

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Update e2e screenshots for basic server examples

277a41b

Updated screenshots to reflect UI changes from styles addition. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Update naming of functions to reflect styles.variables nesting

8f591b6

martinalong dismissed antonpk1’s stale review via 8f591b6 December 15, 2025 19:43

martinalong force-pushed the martinalong/mcp-apps/add-styles branch from 4333ec0 to 8f591b6 Compare December 15, 2025 19:43

antonpk1 approved these changes Dec 15, 2025

View reviewed changes

martinalong merged commit e316259 into main Dec 15, 2025
9 checks passed

[MCP Apps] Add styles prop to host context #127

[MCP Apps] Add styles prop to host context #127

Uh oh!

Conversation

martinalong commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Request for input

Uh oh!

pkg-pr-new bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochafik Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

liady Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liady commented Dec 11, 2025

Uh oh!

martinalong commented Dec 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

martinalong Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

martinalong Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

martinalong Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

antonpk1 left a comment

Choose a reason for hiding this comment

Uh oh!

martinalong commented Dec 15, 2025

Uh oh!

liady commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

[MCP Apps] Add `styles` prop to host context #127

[MCP Apps] Add `styles` prop to host context #127

martinalong commented Dec 10, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 10, 2025 •

edited

Loading

liady Dec 11, 2025 •

edited

Loading

martinalong commented Dec 14, 2025 •

edited

Loading

liady commented Dec 15, 2025 •

edited

Loading