Add App To Server

Add UI to MCP Server

Enrich an existing MCP server's tools with interactive UIs using the MCP Apps SDK (@modelcontextprotocol/ext-apps).

How It Works

Existing tools get paired with HTML resources that render inline in the host's conversation. The tool continues to work for text-only clients — UI is an enhancement, not a replacement. Each tool that benefits from UI gets linked to a resource via _meta.ui.resourceUri, and the host renders that resource in a sandboxed iframe when the tool is called.

Getting Reference Code

Clone the SDK repository for working examples and API documentation:

git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps

API Reference (Source Files)

Read JSDoc documentation directly from /tmp/mcp-ext-apps/src/:

Key Examples (Mixed Tool Patterns)

These examples demonstrate servers with both App-enhanced and plain tools — the exact pattern you're adding:

Framework Templates

Learn and adapt from /tmp/mcp-ext-apps/examples/basic-server-{framework}/:

Step 1: Analyze Existing Tools

Before writing any code, analyze the server's existing tools and determine which ones benefit from UI.

1. Read the server source and list all registered tools
2. For each tool, assess whether it would benefit from UI (returns data that could be visualized, involves user interaction, etc.) vs. is fine as text-only (simple lookups, utility functions)
3. Identify tools that could become app-only helpers (data the UI needs to poll/fetch but the model doesn't need to call directly)
4. Present the analysis to the user and confirm which tools to enhance

Decision Framework

Step 2: Add Dependencies

npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@^2.0.0 @modelcontextprotocol/server@^2.0.0 zod@^4.2.0
npm install -D vite vite-plugin-singlefile

Plus framework-specific dependencies if needed (e.g., react, react-dom, @vitejs/plugin-react for React), and @modelcontextprotocol/node / @modelcontextprotocol/express if the server uses HTTP transports.

ext-apps 2.x requires the split base MCP SDK packages at ^2.0.0 (@modelcontextprotocol/core comes in transitively). Existing servers that still import @modelcontextprotocol/sdk v1 must migrate those imports and handler schemas before adding the App integration:

Step 3: Set Up the Build Pipeline

Vite Configuration

Create vite.config.ts with vite-plugin-singlefile to bundle the UI into a single HTML file:

import { defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [viteSingleFile()],
  build: {
    outDir: "dist",
    rollupOptions: {
      input: "mcp-app.html", // one per UI, or one shared entry
    },
  },
});

HTML Entry Point

Create mcp-app.html (or one per distinct UI if tools need different views):

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>MCP App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./src/mcp-app.ts"></script>
  </body>
</html>

Build Scripts

Add build scripts to package.json. The UI must be built before the server code bundles it:

{
  "scripts": {
    "build:ui": "vite build",
    "build:server": "tsc",
    "build": "npm run build:ui && npm run build:server",
    "serve": "tsx server.ts"
  }
}

Step 4: Convert Tools to App Tools

Transform plain MCP tools into App tools with UI.

Before (plain MCP tool):

server.registerTool(
  "my-tool",
  { inputSchema: z.object({ param: z.string() }) },
  async ({ param }) => {
    const data = await fetchData(param);
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  },
);

After (App tool with UI):

import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

const resourceUri = "ui://my-tool/mcp-app.html";

registerAppTool(
  server,
  "my-tool",
  {
    description: "Shows data with an interactive UI",
    inputSchema: z.object({ param: z.string() }),
    _meta: { ui: { resourceUri } },
  },
  async ({ param }) => {
    const data = await fetchData(param);
    return {
      content: [{ type: "text", text: JSON.stringify(data) }], // text fallback for non-UI hosts
      structuredContent: { data }, // structured data for the UI
    };
  },
);

Key guidance:

• Always keep the `content` array with a text fallback for text-only clients
• Add structuredContent for data the UI needs to render
• Link the tool to its resource via _meta.ui.resourceUri
• Leave tools that don't benefit from UI unchanged — they stay as plain tools

Step 5: Register Resources

Register the HTML resource so the host can fetch it:

import fs from "node:fs/promises";