Add MCP Apps hello world demo tool

Implements a simple MCP Apps tool that returns an interactive React UI:

- Add `mcp_apps_hello_world` tool with `_meta.ui/resourceUri` metadata
- Add resource handler for `ui://hello-world/app.html` returning HTML
- Create React app using `@modelcontextprotocol/ext-apps/react` hooks
- Add Vite build tooling to bundle React apps into single HTML files

The tool demonstrates the MCP Apps extension (SEP-1865) which allows
MCP servers to return interactive UI that runs in the client.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

package.json

@@ -8,7 +8,8 @@
     "dev": "tsx watch --inspect src/index.ts",
     "dev:internal": "AUTH_MODE=internal tsx watch --inspect src/index.ts",
     "dev:external": "concurrently \"AUTH_MODE=auth_server PORT=3001 BASE_URI=http://localhost:3001 tsx watch src/index.ts\" \"sleep 3 && AUTH_MODE=external AUTH_SERVER_URL=http://localhost:3001 tsx watch --inspect src/index.ts\"",
-    "build": "tsc && npm run copy-static",
+    "build": "tsc && npm run copy-static && npm run build:apps",
+    "build:apps": "INPUT=src/apps/hello-world/mcp-app.html vite build",
     "copy-static": "mkdir -p dist/static dist/modules/auth/static && cp -r src/static/* dist/static/ 2>/dev/null || true && cp src/modules/auth/static/mcp.png dist/modules/auth/static/ 2>/dev/null || true",
     "start": "node dist/index.js",
     "start:internal": "AUTH_MODE=internal npm start",
@@ -22,13 +23,17 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@95663d4",
     "@modelcontextprotocol/sdk": "^1.24.2",
     "@redis/client": "^1.6.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
     "express-rate-limit": "^8.0.1",
-    "raw-body": "^3.0.0"
+    "raw-body": "^3.0.0",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^9.15.0",
@@ -37,12 +42,17 @@
     "@types/express": "^5.0.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.10.0",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
     "concurrently": "^8.2.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.0"
+    "typescript-eslint": "^8.18.0",
+    "vite": "^5.4.21",
+    "vite-plugin-singlefile": "^2.3.0"
   },
   "overrides": {
     "@types/express": "^5.0.0",

src/apps/hello-world/App.tsx

@@ -0,0 +1,126 @@
+/**
+ * Simple Hello World MCP App demonstrating the ext-apps SDK with React.
+ */
+import { useApp } from "@modelcontextprotocol/ext-apps/react";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { StrictMode, useState } from "react";
+import { createRoot } from "react-dom/client";
+
+const IMPLEMENTATION = { name: "Hello World App", version: "1.0.0" };
+
+function HelloWorldApp() {
+  const [toolInput, setToolInput] = useState<Record<string, unknown> | null>(null);
+  const [toolResult, setToolResult] = useState<CallToolResult | null>(null);
+
+  const { app, error } = useApp({
+    appInfo: IMPLEMENTATION,
+    capabilities: {},
+    onAppCreated: (app) => {
+      app.ontoolinput = async (input) => {
+        console.log("[HelloWorldApp] Received tool input:", input);
+        setToolInput(input.arguments ?? {});
+      };
+
+      app.ontoolresult = async (result) => {
+        console.log("[HelloWorldApp] Received tool result:", result);
+        setToolResult(result);
+      };
+
+      app.onerror = (err) => console.error("[HelloWorldApp] Error:", err);
+    },
+  });
+
+  if (error) {
+    return (
+      <div style={styles.container}>
+        <h1 style={styles.error}>Error</h1>
+        <p>{error.message}</p>
+      </div>
+    );
+  }
+
+  if (!app) {
+    return (
+      <div style={styles.container}>
+        <p>Connecting to host...</p>
+      </div>
+    );
+  }
+
+  return (
+    <div style={styles.container}>
+      <h1 style={styles.title}>Hello World MCP App</h1>
+
+      <section style={styles.section}>
+        <h2>Tool Input</h2>
+        {toolInput ? (
+          <pre style={styles.code}>{JSON.stringify(toolInput, null, 2)}</pre>
+        ) : (
+          <p style={styles.muted}>Waiting for tool input...</p>
+        )}
+      </section>
+
+      <section style={styles.section}>
+        <h2>Tool Result</h2>
+        {toolResult ? (
+          <pre style={styles.code}>{JSON.stringify(toolResult, null, 2)}</pre>
+        ) : (
+          <p style={styles.muted}>Waiting for tool result...</p>
+        )}
+      </section>
+
+      <section style={styles.section}>
+        <h2>Actions</h2>
+        <button
+          style={styles.button}
+          onClick={() => app.sendMessage({
+            role: "user",
+            content: [{ type: "text", text: "Hello from MCP App!" }]
+          })}
+        >
+          Send Message to Chat
+        </button>
+      </section>
+    </div>
+  );
+}
+
+const styles: Record<string, React.CSSProperties> = {
+  container: {
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    padding: "1rem",
+    maxWidth: "600px",
+  },
+  title: {
+    margin: "0 0 1rem 0",
+    fontSize: "1.5rem",
+  },
+  section: {
+    marginBottom: "1.5rem",
+  },
+  code: {
+    background: "#f4f4f4",
+    padding: "0.75rem",
+    borderRadius: "4px",
+    fontSize: "0.875rem",
+    overflow: "auto",
+  },
+  muted: {
+    color: "#666",
+    fontStyle: "italic",
+  },
+  button: {
+    padding: "0.5rem 1rem",
+    fontSize: "1rem",
+    cursor: "pointer",
+  },
+  error: {
+    color: "#c00",
+  },
+};
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <HelloWorldApp />
+  </StrictMode>
+);

src/apps/hello-world/mcp-app.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hello World MCP App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./App.tsx"></script>
+  </body>
+</html>

src/modules/mcp/services/mcp.ts

@@ -1,4 +1,6 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import fs from "node:fs/promises";
+import path from "node:path";
 import {
   CallToolRequestSchema,
   CompleteRequestSchema,
@@ -18,7 +20,7 @@ import {
   Tool,
   UnsubscribeRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 type ToolInput = Tool["inputSchema"];
 
@@ -90,8 +92,13 @@ enum ToolName {
   ANNOTATED_MESSAGE = "annotatedMessage",
   GET_RESOURCE_REFERENCE = "getResourceReference",
   ELICIT_INPUTS = "elicitInputs",
+  MCP_APPS_HELLO_WORLD = "mcp_apps_hello_world",
 }
 
+// MCP Apps constants
+const RESOURCE_URI_META_KEY = "ui/resourceUri";
+const HELLO_WORLD_APP_URI = "ui://hello-world/app.html";
+
 enum PromptName {
   SIMPLE = "simple_prompt",
   COMPLEX = "complex_prompt",
@@ -274,6 +281,21 @@ export const createMcpServer = (): McpServerWrapper => {
       }
     }
 
+    // MCP Apps UI resources
+    if (uri === HELLO_WORLD_APP_URI) {
+      const distDir = path.join(import.meta.dirname, "../../../apps");
+      const html = await fs.readFile(path.join(distDir, "mcp-app.html"), "utf-8");
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/html;profile=mcp-app",
+            text: html,
+          },
+        ],
+      };
+    }
+
     throw new Error(`Unknown resource: ${uri}`);
   });
 
@@ -455,6 +477,13 @@ export const createMcpServer = (): McpServerWrapper => {
           "Elicitation test tool that demonstrates how to request user input with various field types",
         inputSchema: { type: "object" , properties: {} },
       },
+      {
+        name: ToolName.MCP_APPS_HELLO_WORLD,
+        description:
+          "Demonstrates MCP Apps - returns an interactive UI that runs in the client",
+        inputSchema: { type: "object", properties: {} },
+        _meta: { [RESOURCE_URI_META_KEY]: HELLO_WORLD_APP_URI },
+      },
     ];
 
     return { tools };
@@ -720,6 +749,18 @@ export const createMcpServer = (): McpServerWrapper => {
       };
     }
 
+    if (name === ToolName.MCP_APPS_HELLO_WORLD) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Hello World MCP App loaded!",
+          },
+        ],
+        _meta: { [RESOURCE_URI_META_KEY]: HELLO_WORLD_APP_URI },
+      };
+    }
+
     throw new Error(`Unknown tool: ${name}`);
   });
 

tsconfig.json

@@ -24,6 +24,7 @@
     "node_modules",
     "dist",
     "**/*.test.ts",
-    "**/*.spec.ts"
+    "**/*.spec.ts",
+    "src/apps/**/*"
   ]
 }

vite.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+import path from "path";
+
+const input = process.env.INPUT;
+if (!input) {
+  throw new Error("INPUT environment variable is required");
+}
+
+export default defineConfig({
+  plugins: [react(), viteSingleFile()],
+  root: path.dirname(input),
+  build: {
+    outDir: path.resolve("dist/apps"),
+    emptyOutDir: false,
+    rollupOptions: {
+      input: input,
+    },
+  },
+});