Merge pull request #159 from modelcontextprotocol/martinalong/mcp-apps/custom-fonts

[MCP Apps] Add way to pass custom fonts

Author: antonpk1

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

@@ -5,6 +5,7 @@ import {
   App,
   PostMessageTransport,
   applyHostStyleVariables,
+  applyHostFonts,
   applyDocumentTheme,
 } from "@modelcontextprotocol/ext-apps";
 import { Chart, registerables } from "chart.js";
@@ -448,14 +449,17 @@ 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) {
     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)) {
     state.chart.destroy();
@@ -472,6 +476,9 @@ app.connect().then(() => {
   if (ctx?.styles?.variables) {
     applyHostStyleVariables(ctx.styles.variables);
   }
+  if (ctx?.styles?.css?.fonts) {
+    applyHostFonts(ctx.styles.css.fonts);
+  }
 });
 
 // Fetch data after connection

specification/draft/apps.mdx

@@ -451,6 +451,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";
@@ -503,8 +508,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",
@@ -638,7 +646,46 @@ Example usage of standardized CSS variables:
 .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
+hostContext.styles.variables["--font-sans"] = '"Font Name", sans-serif';
+
+// Self-hosted fonts
+hostContext.styles.css.fonts = `
+  @font-face {
+    font-family: "Font Name";
+    src: url("https://url-where-font-is-hosted.com/.../Regular.otf") format("opentype");
+    font-weight: 400;
+    font-style: normal;
+    font-display: swap;
+  }
+  @font-face {
+    font-family: "Font Name";
+    src: url("https://url-where-font-is-hosted.com/.../Medium.otf") format("opentype");
+    font-weight: 500;
+    font-style: medium;
+    font-display: swap;
+  }
+`;
+
+// Google Fonts
+hostContext.styles.css.fonts = `
+  @import url('https://fonts.googleapis.com/css2?family=Font+Name&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

@@ -52,6 +52,7 @@ export { PostMessageTransport } from "./message-transport";
 export * from "./types";
 export {
   applyHostStyleVariables,
+  applyHostFonts,
   getDocumentTheme,
   applyDocumentTheme,
 } from "./styles";

src/generated/schema.json

@@ -10,6 +10,7 @@
  *
  * - {@link useApp} - React hook to create and connect an MCP App
  * - {@link useHostStyleVariables} - React hook to apply host style variables and theme
+ * - {@link useHostFonts} - React hook to apply host fonts
  * - {@link useDocumentTheme} - React hook for reactive document theme
  * - {@link useAutoResize} - React hook for manual auto-resize control (rarely needed)
  *