Add way to pass fonts

Author: martinalong

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

@@ -2,6 +2,9 @@
 :root {
   color-scheme: light dark;
 
+  /* Font families */
+  --font-sans: system-ui, -apple-system, sans-serif;
+
   /* Background colors */
   --color-background-primary: light-dark(#ffffff, #111827);
   --color-background-secondary: light-dark(#f9fafb, #1f2937);
@@ -33,6 +36,7 @@
 html, body {
   margin: 0;
   padding: 0;
+  font-family: var(--font-sans);
   color: var(--color-text-primary);
   overflow: hidden;
 }

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

@@ -4,7 +4,8 @@
 import {
   App,
   PostMessageTransport,
-  applyHostStyles,
+  applyHostStyleVariables,
+  applyHostFonts,
   applyDocumentTheme,
 } from "@modelcontextprotocol/ext-apps";
 import { Chart, registerables } from "chart.js";
@@ -448,13 +449,16 @@ applyDocumentTheme(systemDark ? "dark" : "light");
 // Register handlers and connect
 app.onerror = log.error;
 
-// Handle host context changes (theme and styles from host)
+// Handle host context changes (theme, styles, and fonts from host)
 app.onhostcontextchanged = (params) => {
   if (params.theme) {
     applyDocumentTheme(params.theme);
   }
   if (params.styles?.variables) {
-    applyHostStyles(params.styles.variables);
+    applyHostStyleVariables(params.styles.variables);
+  }
+  if (params.styles?.css?.fonts) {
+    applyHostFonts(params.styles.css.fonts);
   }
   // Recreate chart to pick up new colors
   if (state.chart && (params.theme || params.styles?.variables)) {
@@ -470,7 +474,10 @@ app.connect(new PostMessageTransport(window.parent)).then(() => {
     applyDocumentTheme(ctx.theme);
   }
   if (ctx?.styles?.variables) {
-    applyHostStyles(ctx.styles.variables);
+    applyHostStyleVariables(ctx.styles.variables);
+  }
+  if (ctx?.styles?.css?.fonts) {
+    applyHostFonts(ctx.styles.css.fonts);
   }
 });
 

specification/draft/apps.mdx

@@ -409,6 +409,11 @@ interface HostContext {
   styles?: {
     /** CSS variables for theming */
     variables?: Record<McpUiStyleVariableKey, string | undefined>;
+    /** CSS blocks that apps can inject */
+    css?: {
+      /** CSS for font loading (@font-face rules or @import statements) */
+      fonts?: string;
+    };
   };
   /** How the UI is currently displayed */
   displayMode?: "inline" | "fullscreen" | "pip";
@@ -461,8 +466,11 @@ Example:
         "variables": {
           "--color-background-primary": "light-dark(#ffffff, #171717)",
           "--color-text-primary": "light-dark(#171717, #fafafa)",
-          "--font-family-sans": "system-ui, sans-serif",
+          "--font-sans": "Anthropic Sans, sans-serif",
           ...
+        },
+        "css": {
+          "fonts": "@font-face { font-family: \"Custom Font Name\"; src: url(\"https://...\"); }"
         }
       },
       "displayMode": "inline",
@@ -587,16 +595,46 @@ type McpUiStyleVariableKey =
   ...
 }
 ```
-- Apps can use the `applyHostStyles` utility (or `useHostStyles` if they prefer a React hook) to easily populate the host-provided CSS variables into their style sheet
-- Apps can use the `applyDocumentTheme` utility (or `useDocumentTheme` if they prefer a React hook) to easily respond to Host Context `theme` changes in a way that is compatible with the host's light/dark color variables 
+- Apps can use the `applyHostStyleVariables` utility (or `useHostStyleVariables` if they prefer a React hook) to easily populate the host-provided CSS variables into their style sheet
+- Apps can use the `applyDocumentTheme` utility (or `useDocumentTheme` if they prefer a React hook) to easily respond to Host Context `theme` changes in a way that is compatible with the host's light/dark color variables
 
 Example usage of standardized CSS variables:
 
 ```css
 .container {
   background: var(--color-background-primary);
   color: var(--color-text-primary);
-  font: var(--font-style-body);
+  font-family: var(--font-sans);
+}
+```
+
+#### Custom Fonts
+
+Hosts can provide custom fonts via `styles.css.fonts`, which can contain `@font-face` rules for self-hosted fonts, `@import` statements for font services like Google Fonts, or both:
+
+```typescript
+// Self-hosted fonts
+hostContext.styles.css.fonts = `
+  @font-face {
+    font-family: "Custom Font Name"; // Name should match the font name used in a font variable (`--font-sans`, `--font-mono`)
+    src: url("https://url-where-font-is-hosted.com/.../Regular.otf") format("opentype");
+    font-weight: 400;
+    font-style: normal;
+    font-display: swap;
+  }
+`;
+
+// Google Fonts
+hostContext.styles.css.fonts = `
+  @import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
+`;
+```
+
+Apps can use the `applyHostFonts` utility to inject the font CSS into the document:
+
+```typescript
+if (hostContext.styles?.css?.fonts) {
+  applyHostFonts(hostContext.styles.css.fonts);
 }
 ```
 

src/app.ts

@@ -48,7 +48,8 @@ import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 export { PostMessageTransport } from "./message-transport";
 export * from "./types";
 export {
-  applyHostStyles,
+  applyHostStyleVariables,
+  applyHostFonts,
   getDocumentTheme,
   applyDocumentTheme,
 } from "./styles";

src/generated/schema.json

@@ -585,6 +585,17 @@
                       {}
                     ]
                   }
+                },
+                "css": {
+                  "description": "CSS blocks that apps can inject.",
+                  "type": "object",
+                  "properties": {
+                    "fonts": {
+                      "description": "CSS for font loading (@font-face rules or",
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
                 }
               },
               "additionalProperties": false
@@ -1196,6 +1207,17 @@
                   {}
                 ]
               }
+            },
+            "css": {
+              "description": "CSS blocks that apps can inject.",
+              "type": "object",
+              "properties": {
+                "fonts": {
+                  "description": "CSS for font loading (@font-face rules or",
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -1319,6 +1341,17 @@
       },
       "additionalProperties": {}
     },
+    "McpUiHostCss": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "fonts": {
+          "description": "CSS for font loading (@font-face rules or",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
     "McpUiHostStyles": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
       "type": "object",
@@ -1640,6 +1673,17 @@
               {}
             ]
           }
+        },
+        "css": {
+          "description": "CSS blocks that apps can inject.",
+          "type": "object",
+          "properties": {
+            "fonts": {
+              "description": "CSS for font loading (@font-face rules or",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -2314,6 +2358,17 @@
                       {}
                     ]
                   }
+                },
+                "css": {
+                  "description": "CSS blocks that apps can inject.",
+                  "type": "object",
+                  "properties": {
+                    "fonts": {
+                      "description": "CSS for font loading (@font-face rules or",
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
                 }
               },
               "additionalProperties": false

src/generated/schema.test.ts

@@ -63,6 +63,10 @@ export type McpUiToolCancelledNotificationSchemaInferredType = z.infer<
   typeof generated.McpUiToolCancelledNotificationSchema
 >;
 
+export type McpUiHostCssSchemaInferredType = z.infer<
+  typeof generated.McpUiHostCssSchema
+>;
+
 export type McpUiHostStylesSchemaInferredType = z.infer<
   typeof generated.McpUiHostStylesSchema
 >;
@@ -181,6 +185,8 @@ expectType<spec.McpUiToolCancelledNotification>(
 expectType<McpUiToolCancelledNotificationSchemaInferredType>(
   {} as spec.McpUiToolCancelledNotification,
 );
+expectType<spec.McpUiHostCss>({} as McpUiHostCssSchemaInferredType);
+expectType<McpUiHostCssSchemaInferredType>({} as spec.McpUiHostCss);
 expectType<spec.McpUiHostStyles>({} as McpUiHostStylesSchemaInferredType);
 expectType<McpUiHostStylesSchemaInferredType>({} as spec.McpUiHostStyles);
 expectType<spec.McpUiResourceTeardownRequest>(

src/generated/schema.ts

@@ -285,6 +285,17 @@ export const McpUiToolCancelledNotificationSchema = z.object({
   }),
 });
 
+/**
+ * @description CSS blocks that can be injected by apps.
+ */
+export const McpUiHostCssSchema = z.object({
+  /** @description CSS for font loading (@font-face rules or @import statements). Apps must apply using applyHostFonts(). */
+  fonts: z
+    .string()
+    .optional()
+    .describe("CSS for font loading (@font-face rules or"),
+});
+
 /**
  * @description Style configuration for theming MCP apps.
  */
@@ -293,6 +304,10 @@ export const McpUiHostStylesSchema = z.object({
   variables: McpUiStylesSchema.optional().describe(
     "CSS variables for theming the app.",
   ),
+  /** @description CSS blocks that apps can inject. */
+  css: McpUiHostCssSchema.optional().describe(
+    "CSS blocks that apps can inject.",
+  ),
 });
 
 /**

src/react/index.tsx

@@ -9,7 +9,9 @@
  * ## Main Exports
  *
  * - {@link useApp} - React hook to create and connect an MCP App
- * - {@link useHostStyles} - React hook to apply host styles as CSS variables
+ * - {@link useHostStyleVariables} - React hook to apply host style variables and theme
+ * - {@link useHostFonts} - React hook to apply host fonts
+ * - {@link useHostStyles} - Convenience hook combining useHostStyleVariables and useHostFonts
  * - {@link useDocumentTheme} - React hook for reactive document theme
  * - {@link useAutoResize} - React hook for manual auto-resize control (rarely needed)
  *