MCP Apps SDK教程：为MCP服务器工具添加交互式UI界面

add-app-to-server by modelcontextprotocol/ext-apps

274 周安装量

2,000 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/modelcontextprotocol/ext-apps --skill add-app-to-server

AI/机器学习开发前端架构

🇨🇳中文介绍

为 MCP 服务器添加用户界面

使用 MCP Apps SDK (@modelcontextprotocol/ext-apps) 为现有的 MCP 服务器工具添加交互式用户界面。

工作原理

现有的工具将与 HTML 资源配对，这些资源在宿主的对话中内联渲染。该工具在纯文本客户端上继续工作——用户界面是一种增强，而非替代。每个能从用户界面中受益的工具都通过 _meta.ui.resourceUri 链接到一个资源，当调用该工具时，宿主会在沙盒化的 iframe 中渲染该资源。

获取参考代码

克隆 SDK 仓库以获取工作示例和 API 文档：

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

API 参考（源文件）

直接从 /tmp/mcp-ext-apps/src/ 阅读 JSDoc 文档：

文件	内容
`src/app.ts`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

关键示例（混合工具模式）

这些示例演示了同时包含应用增强工具和纯文本工具的服务器——这正是您要添加的模式：

示例	模式
`examples/map-server/`	`show-map` (应用工具) + `geocode` (纯文本工具)
`examples/pdf-server/`	`display_pdf` (应用工具) + `list_pdfs` (纯文本工具) + `read_pdf_bytes` (仅应用工具)
`examples/system-monitor-server/`	`get-system-info` (应用工具) + `poll-system-stats` (仅应用轮询工具)

从 /tmp/mcp-ext-apps/examples/basic-server-{framework}/ 学习并适配：

模板	关键文件
`basic-server-vanillajs/`	`server.ts`, `src/mcp-app.ts`, `mcp-app.html`
`basic-server-react/`	`server.ts`, `src/mcp-app.tsx` (使用 `useApp` 钩子)
`basic-server-vue/`	`server.ts`, `src/App.vue`
`basic-server-svelte/`	`server.ts`, `src/App.svelte`
`basic-server-preact/`	`server.ts`, `src/mcp-app.tsx`
`basic-server-solid/`	`server.ts`, `src/mcp-app.tsx`

步骤 1：分析现有工具

在编写任何代码之前，分析服务器的现有工具并确定哪些工具能从用户界面中受益。

阅读服务器源代码并列出所有已注册的工具
对于每个工具，评估它是否能从用户界面中受益（返回可可视化的数据、涉及用户交互等）还是作为纯文本工具即可（简单的查找、实用函数）
识别可能成为仅应用辅助工具的工具（用户界面需要轮询/获取但模型不需要直接调用的数据）
向用户展示分析结果并确认要增强哪些工具

工具输出类型	用户界面收益	示例
结构化数据 / 列表 / 表格	高 — 交互式表格、搜索、筛选	项目列表、搜索结果
随时间变化的指标 / 数字	高 — 图表、仪表盘、仪表板	系统统计、分析数据
媒体 / 富内容	高 — 查看器、播放器、渲染器	地图、PDF、图像、视频
简单文本 / 确认信息	低 — 文本即可	"文件已创建"、"设置已更新"
供其他工具使用的数据	考虑设为仅应用工具	轮询端点、分块加载器

步骤 2：添加依赖项

npm install @modelcontextprotocol/ext-apps
npm install -D vite vite-plugin-singlefile

如果需要，还需添加框架特定的依赖项（例如，对于 React，需要 react、react-dom、@vitejs/plugin-react）。

使用 npm install 添加依赖项，而不是手动编写版本号。这可以让 npm 解析最新的兼容版本。切勿凭记忆指定版本号。

步骤 3：设置构建流水线

创建 vite.config.ts，使用 vite-plugin-singlefile 将用户界面打包成单个 HTML 文件：

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

export default defineConfig({
  plugins: [viteSingleFile()],
  build: {
    outDir: "dist",
    rollupOptions: {
      input: "mcp-app.html", // 每个用户界面一个入口，或一个共享入口
    },
  },
});

创建 mcp-app.html（如果工具需要不同的视图，则为每个独立的用户界面创建一个）：

<!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>

将构建脚本添加到 package.json。必须在服务器代码打包之前构建用户界面：

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

步骤 4：将工具转换为应用工具

将纯 MCP 工具转换为带有用户界面的应用工具。

之前（纯 MCP 工具）：

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

之后（带有用户界面的应用工具）：

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: { param: z.string() },
  _meta: { ui: { resourceUri } },
}, async (args) => {
  const data = await fetchData(args.param);
  return {
    content: [{ type: "text", text: JSON.stringify(data) }],   // 为非用户界面宿主准备的文本回退方案
    structuredContent: { data },                                 // 供用户界面使用的结构化数据
  };
});

始终保留content 数组，为非用户界面宿主提供文本回退方案
添加 structuredContent 用于用户界面渲染所需的数据
通过 _meta.ui.resourceUri 将工具链接到其资源
保持那些无法从用户界面中受益的工具不变——它们仍然是纯文本工具

步骤 5：注册资源

import fs from "node:fs/promises";
import path from "node:path";

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

registerAppResource(server, {
  uri: resourceUri,
  name: "My Tool UI",
  mimeType: RESOURCE_MIME_TYPE,
}, async () => {
  const html = await fs.readFile(
    path.resolve(import.meta.dirname, "dist", "mcp-app.html"),
    "utf-8",
  );
  return { contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }] };
});

如果多个工具共享同一个用户界面，它们可以引用相同的 resourceUri 和相同的资源注册。

步骤 6：构建用户界面

在调用 app.connect() 之前注册所有处理器：

import { App, PostMessageTransport, applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";

const app = new App({ name: "My App", version: "1.0.0" });

app.ontoolinput = (params) => {
  // 使用 params.arguments 和/或 params.structuredContent 渲染用户界面
};

app.ontoolresult = (result) => {
  // 使用最终的工具结果更新用户界面
};

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  if (ctx.safeAreaInsets) {
    const { top, right, bottom, left } = ctx.safeAreaInsets;
    document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
  }
};

app.onteardown = async () => {
  return {};
};

await app.connect(new PostMessageTransport());

使用宿主 CSS 变量进行主题集成：

.container {
  background: var(--color-background-secondary);
  color: var(--color-text-primary);
  font-family: var(--font-sans);
  border-radius: var(--border-radius-md);
}

关键变量组：--color-background-*, --color-text-*, --color-border-*, --font-sans, --font-mono, --font-text-*-size, --font-heading-*-size, --border-radius-*。完整列表请参见 src/spec.types.ts。

对于 React 应用，请使用 useApp 和 useHostStyles 钩子替代——请参考 basic-server-react/ 中的模式。

仅应用辅助工具

用户界面调用但模型不需要直接调用的工具（轮询、分页、分块加载）：

registerAppTool(server, "poll-data", {
  description: "Polls latest data for the UI",
  _meta: { ui: { resourceUri, visibility: ["app"] } },
}, async () => {
  const data = await getLatestData();
  return { content: [{ type: "text", text: JSON.stringify(data) }] };
});

用户界面通过 app.callServerTool("poll-data", {}) 调用这些工具。

如果用户界面需要加载外部资源（字体、API、CDN），请声明域名：

registerAppResource(server, {
  uri: resourceUri,
  name: "My Tool UI",
  mimeType: RESOURCE_MIME_TYPE,
  _meta: {
    ui: {
      connectDomains: ["api.example.com"],      // fetch/XHR 目标
      resourceDomains: ["cdn.example.com"],      // 脚本、样式、图像
      frameDomains: ["embed.example.com"],        // 嵌套 iframe
    },
  },
}, async () => { /* ... */ });

流式传输部分输入

对于大型工具输入，在 LLM 生成过程中显示进度：

app.ontoolinputpartial = (params) => {
  const args = params.arguments; // 已修复的部分 JSON - 始终有效
  // 使用部分数据渲染预览
};

app.ontoolinput = (params) => {
  // 最终完整的输入 - 切换到完整渲染
};

使用 `getUiCapability()` 进行优雅降级

仅在客户端支持用户界面时有条件地注册应用工具，否则回退到纯文本工具：

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

server.server.oninitialized = () => {
  const clientCapabilities = server.server.getClientCapabilities();
  const uiCap = getUiCapability(clientCapabilities);

  if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
    // 客户端支持用户界面 — 注册应用工具
    registerAppTool(server, "my-tool", {
      description: "Shows data with interactive UI",
      _meta: { ui: { resourceUri } },
    }, appToolHandler);
  } else {
    // 纯文本客户端 — 注册纯文本工具
    server.tool("my-tool", "Shows data", { param: z.string() }, plainToolHandler);
  }
};

允许用户界面扩展到全屏：

app.onhostcontextchanged = (ctx) => {
  if (ctx.availableDisplayModes?.includes("fullscreen")) {
    fullscreenBtn.style.display = "block";
  }
  if (ctx.displayMode) {
    container.classList.toggle("fullscreen", ctx.displayMode === "fullscreen");
  }
};

async function toggleFullscreen() {
  const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen";
  const result = await app.requestDisplayMode({ mode: newMode });
  currentMode = result.mode;
}

需要避免的常见错误

忘记文本content 回退 — 始终为非用户界面宿主包含带有文本的 content 数组
在connect() 之后注册处理器 — 在调用 app.connect() 之前注册所有处理器
缺少vite-plugin-singlefile — 没有它，资源将无法在沙盒化的 iframe 中加载
忘记资源注册 — 工具引用的 resourceUri 必须有一个匹配的资源
硬编码样式 — 使用宿主 CSS 变量 (var(--color-*)) 进行主题集成
未处理安全区域边距 — 始终在 onhostcontextchanged 中应用 ctx.safeAreaInsets

使用 basic-host 示例测试增强后的服务器：

# 终端 1：构建并运行您的服务器
npm run build && npm run serve

# 终端 2：运行 basic-host（从克隆的仓库）
cd /tmp/mcp-ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3001/mcp"]' npm run start
# 打开 http://localhost:8080

使用您的服务器 URL 的 JSON 数组配置 SERVERS（默认值：http://localhost:3001/mcp）。

纯文本工具仍然有效并返回文本输出
应用工具在 iframe 中渲染其用户界面
ontoolinput 处理器随工具参数触发
ontoolresult 处理器随工具结果触发
宿主样式（主题、字体、颜色）正确应用

2026 年 2 月 21 日

🇺🇸English

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/:

File	Contents
`src/app.ts`	`App` class, handlers (`ontoolinput`, `ontoolresult`, `onhostcontextchanged`, `onteardown`), lifecycle
`src/server/index.ts`	`registerAppTool`, `registerAppResource`, `getUiCapability`, tool visibility options
`src/spec.types.ts`	All type definitions: `McpUiHostContext`, CSS variable keys, display modes
`src/styles.ts`	`applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts`
`src/react/useApp.tsx`	`useApp` hook for React apps
`src/react/useHostStyles.ts`	`useHostStyles`, `useHostStyleVariables`, `useHostFonts` hooks

Key Examples (Mixed Tool Patterns)

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

Example	Pattern
`examples/map-server/`	`show-map` (App tool) + `geocode` (plain tool)
`examples/pdf-server/`	`display_pdf` (App tool) + `list_pdfs` (plain tool) + `read_pdf_bytes` (app-only tool)
`examples/system-monitor-server/`	(App tool) + (app-only polling tool)

Framework Templates

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

Template	Key Files
`basic-server-vanillajs/`	`server.ts`, `src/mcp-app.ts`, `mcp-app.html`
`basic-server-react/`	`server.ts`, `src/mcp-app.tsx` (uses `useApp` hook)
`basic-server-vue/`

Step 1: Analyze Existing Tools

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

Read the server source and list all registered tools
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)
Identify tools that could become app-only helpers (data the UI needs to poll/fetch but the model doesn't need to call directly)
Present the analysis to the user and confirm which tools to enhance

Decision Framework

Tool output type	UI benefit	Example
Structured data / lists / tables	High — interactive table, search, filtering	List of items, search results
Metrics / numbers over time	High — charts, gauges, dashboards	System stats, analytics
Media / rich content	High — viewer, player, renderer	Maps, PDFs, images, video
Simple text / confirmations	Low — text is fine	"File created", "Setting updated"
Data for other tools	Consider app-only	Polling endpoints, chunk loaders

Step 2: Add Dependencies

npm install @modelcontextprotocol/ext-apps
npm install -D vite vite-plugin-singlefile

Plus framework-specific dependencies if needed (e.g., react, react-dom, @vitejs/plugin-react for React).

Use npm install to add dependencies rather than manually writing version numbers. This lets npm resolve the latest compatible versions. Never specify version numbers from memory.

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.tool("my-tool", { param: z.string() }, async (args) => {
  const data = await fetchData(args.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: { param: z.string() },
  _meta: { ui: { resourceUri } },
}, async (args) => {
  const data = await fetchData(args.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 thecontent 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

import fs from "node:fs/promises";
import path from "node:path";

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

registerAppResource(server, {
  uri: resourceUri,
  name: "My Tool UI",
  mimeType: RESOURCE_MIME_TYPE,
}, async () => {
  const html = await fs.readFile(
    path.resolve(import.meta.dirname, "dist", "mcp-app.html"),
    "utf-8",
  );
  return { contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }] };
});

If multiple tools share the same UI, they can reference the same resourceUri and the same resource registration.

Step 6: Build the UI

Handler Registration

import { App, PostMessageTransport, applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";

const app = new App({ name: "My App", version: "1.0.0" });

app.ontoolinput = (params) => {
  // Render the UI using params.arguments and/or params.structuredContent
};

app.ontoolresult = (result) => {
  // Update UI with final tool result
};

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  if (ctx.safeAreaInsets) {
    const { top, right, bottom, left } = ctx.safeAreaInsets;
    document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
  }
};

app.onteardown = async () => {
  return {};
};

await app.connect(new PostMessageTransport());

Host Styling

Use host CSS variables for theme integration:

.container {
  background: var(--color-background-secondary);
  color: var(--color-text-primary);
  font-family: var(--font-sans);
  border-radius: var(--border-radius-md);
}

Key variable groups: --color-background-*, --color-text-*, --color-border-*, --font-sans, --font-mono, --font-text-*-size, --font-heading-*-size, --border-radius-*. See src/spec.types.ts for the full list.

For React apps, use the useApp and useHostStyles hooks instead — see basic-server-react/ for the pattern.

Optional Enhancements

App-Only Helper Tools

Tools the UI calls but the model doesn't need to invoke directly (polling, pagination, chunk loading):

registerAppTool(server, "poll-data", {
  description: "Polls latest data for the UI",
  _meta: { ui: { resourceUri, visibility: ["app"] } },
}, async () => {
  const data = await getLatestData();
  return { content: [{ type: "text", text: JSON.stringify(data) }] };
});

The UI calls these via app.callServerTool("poll-data", {}).

CSP Configuration

If the UI needs to load external resources (fonts, APIs, CDNs), declare the domains:

registerAppResource(server, {
  uri: resourceUri,
  name: "My Tool UI",
  mimeType: RESOURCE_MIME_TYPE,
  _meta: {
    ui: {
      connectDomains: ["api.example.com"],      // fetch/XHR targets
      resourceDomains: ["cdn.example.com"],      // scripts, styles, images
      frameDomains: ["embed.example.com"],        // nested iframes
    },
  },
}, async () => { /* ... */ });

Streaming Partial Input

For large tool inputs, show progress during LLM generation:

app.ontoolinputpartial = (params) => {
  const args = params.arguments; // Healed partial JSON - always valid
  // Render preview with partial data
};

app.ontoolinput = (params) => {
  // Final complete input - switch to full render
};

Graceful Degradation with `getUiCapability()`

Conditionally register App tools only when the client supports UI, falling back to text-only tools:

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

server.server.oninitialized = () => {
  const clientCapabilities = server.server.getClientCapabilities();
  const uiCap = getUiCapability(clientCapabilities);

  if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
    // Client supports UI — register App tool
    registerAppTool(server, "my-tool", {
      description: "Shows data with interactive UI",
      _meta: { ui: { resourceUri } },
    }, appToolHandler);
  } else {
    // Text-only client — register plain tool
    server.tool("my-tool", "Shows data", { param: z.string() }, plainToolHandler);
  }
};

Fullscreen Mode

Allow the UI to expand to fullscreen:

app.onhostcontextchanged = (ctx) => {
  if (ctx.availableDisplayModes?.includes("fullscreen")) {
    fullscreenBtn.style.display = "block";
  }
  if (ctx.displayMode) {
    container.classList.toggle("fullscreen", ctx.displayMode === "fullscreen");
  }
};

async function toggleFullscreen() {
  const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen";
  const result = await app.requestDisplayMode({ mode: newMode });
  currentMode = result.mode;
}

Common Mistakes to Avoid

Forgetting textcontent fallback — Always include content array with text for non-UI hosts
Registering handlers afterconnect() — Register ALL handlers BEFORE calling app.connect()
Missingvite-plugin-singlefile — Without it, assets won't load in the sandboxed iframe
Forgetting resource registration — The tool references a resourceUri that must have a matching resource
Hardcoding styles — Use host CSS variables (var(--color-*)) for theme integration
Not handling safe area insets — Always apply ctx.safeAreaInsets in

Testing

Using basic-host

Test the enhanced server with the basic-host example:

# Terminal 1: Build and run your server
npm run build && npm run serve

# Terminal 2: Run basic-host (from cloned repo)
cd /tmp/mcp-ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3001/mcp"]' npm run start
# Open http://localhost:8080

Configure SERVERS with a JSON array of your server URLs (default: http://localhost:3001/mcp).

Verify

Plain tools still work and return text output
App tools render their UI in the iframe
ontoolinput handler fires with tool arguments
ontoolresult handler fires with tool result
Host styling (theme, fonts, colors) applies correctly

Weekly Installs

185

Repository

modelcontextpro…ext-apps

GitHub Stars

1.9K

First Seen

Feb 21, 2026

Security Audits

Gen Agent Trust HubPass SocketWarn SnykPass

Installed on

cursor178

opencode177

codex177

gemini-cli176

kimi-cli175

github-copilot175

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

onhostcontextchanged