1. 从 add-app-to-server 说起服务器面板为什么需要 UI 增强如果你维护过服务器管理面板大概率遇到过这种尴尬后端工具函数写得挺全add-app-to-server能把应用注册进服务器、能返回 JSON、能跑通命令行但一到面板上就只剩一行行纯文本。运维同事想看某个应用的运行状态得自己复制 JSON 去别处解析想触发一次部署还得记住参数顺序手敲命令。工具是能用的体验却停在十年前。add-app-to-server这类工具的本质是「把外部应用挂到服务器上」它天然带着一堆结构化数据应用 ID、端口、健康检查地址、依赖服务、启动日志。这些数据用文本返回没问题但用表格、状态灯、日志滚动窗口来呈现信息密度和可读性完全不是一个量级。问题在于很多团队不敢动现有工具——怕改了返回格式命令行脚本和自动化流水线全挂掉。MCP Apps SDKmodelcontextprotocol/ext-apps给出的思路正好绕开这个顾虑UI 是叠加层不是替代品。每个工具照旧返回content文本数组纯文本客户端一切如常同时通过_meta.ui.resourceUri挂一个 HTML 资源支持 UI 的宿主在调用工具时把这个资源塞进沙箱 iframe 里渲染。工具还是那个工具只是多了一张脸。这套机制落到服务器面板场景价值就很具体了。你可以把add-app-to-server的返回结果做成一张应用卡片左边状态徽章右边端口和健康检查链接底部一个「重新加载」按钮直接调app.callServerTool。命令行用户看到的还是那段 JSON面板用户看到的是可点的界面。同一份工具实现两种消费方式。我试过在一个内部运维面板上按这个思路改造最直观的收益是排障时间。以前查一个应用为什么没起来要在三四个工具之间来回切、手动比对返回现在一个 iframe 里把add-app-to-server的结果、轮询到的实时状态、最近日志拼在一起问题定位从几分钟压到几十秒。下面就把这套流程拆成可复制的步骤从依赖安装到本地验证走一遍。2. TaoToken 前置准备把模型调用和工具注册串起来在动手写 iframe 和 MCP 工具之前得先把「谁来驱动这些工具」这件事定下来。服务器面板的 UI 增强本身不依赖某个特定模型但你要在本地验证add-app-to-server的 UI 渲染、测试ontoolinput/ontoolresult回调是否按预期触发就需要一个能稳定调用工具、支持 MCP 协议的模型入口。TaoToken 在这里扮演的是统一接入层的角色一个 Base URL、一个 Key就能把对话模型和编码类模型都接进来省去在多个平台之间来回切换配置的麻烦。先说清楚它适合谁。如果你只是想让面板上的 iframe 能渲染出来其实不需要模型——basic-host直接连你的 MCP server 就能看到 UI。但真实场景里工具调用往往由模型发起用户说「把订单服务挂到测试服务器上」模型解析意图、调用add-app-to-server、拿到结构化结果宿主再把结果喂给 iframe 渲染。这条链路里模型是触发器。TaoToken 的价值就是让这个触发器足够稳、切换足够便宜。接入方式很直接。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。这个 Key 就是你后面所有配置里的凭证。注意Key 只在创建时完整显示一次复制好放本地环境变量别写进代码提交。拿到 Key 之后Base URL 统一用 https://taotoken.net/api这个地址不加 UTM 参数配置里照抄即可。模型 ID 按你的场景选纯对话验证用通用对话模型长期跑编码和 Agent 任务可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你用的是 Claude Code 这类工具接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有对应的环境变量写法。这里有个容易踩的坑很多人把模型接入和 MCP server 的启动混在一起配结果add-app-to-server的 UI 资源加载失败却以为是模型的问题。实际上这两条线是分开的——模型负责「决定调哪个工具」MCP server 负责「工具怎么执行、UI 资源从哪来」。TaoToken 只管前一条线。把这条线配通后面调试 iframe 通信时就能排除掉模型层的干扰。配置完建议先做一次最小验证用模型对话 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条简单请求确认 Key 和 Base URL 生效。这一步过了再往下走工具注册和 iframe 渲染出问题时排查范围会小很多。3. 可复制配置iframe 通信、MCP 工具注册与构建管线这一节是全文的技术核心我会把add-app-to-server改造成带 UI 的 App 工具并给出完整的配置文件。所有片段都可以直接复制路径和原文保持一致。3.1 依赖与构建配置先装依赖。用 npm 让它自己解析兼容版本别手写版本号npm install modelcontextprotocol/ext-apps npm install -D vite vite-plugin-singlefile如果你用 React 写 UI再加react、react-dom、vitejs/plugin-react。核心是vite-plugin-singlefile——它把 JS、CSS 全部内联进一个 HTML 文件。这一步不能省因为 iframe 是沙箱化的外部资源路径在宿主里加载不到资源必须自包含。vite.config.ts配置如下注意input指向你的 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是 UI 的挂载点!doctype html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleadd-app-to-server UI/title /head body div idroot/div script typemodule src./src/mcp-app.ts/script /body /htmlpackage.json的脚本要保证 UI 先于 server 构建否则 server 打包时读不到dist/mcp-app.html{ scripts: { build:ui: vite build, build:server: tsc, build: npm run build:ui npm run build:server, serve: tsx server.ts } }3.2 把 add-app-to-server 改成 App 工具改造前它是普通工具返回纯文本。改造后保留文本回退同时加structuredContent和资源链接import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from modelcontextprotocol/ext-apps/server import { z } from zod const resourceUri ui://add-app-to-server/mcp-app.html registerAppTool( server, add-app-to-server, { description: 将外部应用注册到服务器返回应用状态与端口信息, inputSchema: { appName: z.string(), port: z.number(), healthPath: z.string().default(/health), }, _meta: { ui: { resourceUri } }, }, async (args) { const data await registerApp(args) return { content: [{ type: text, text: JSON.stringify(data) }], structuredContent: { data }, } } )三个要点content数组必须保留纯文本客户端靠它structuredContent是给 iframe 用的结构化数据_meta.ui.resourceUri把工具和资源绑死URI 必须和下面注册的一致。3.3 注册 HTML 资源宿主拿到resourceUri后要能取到 HTML所以资源注册不能漏import fs from node:fs/promises import path from node:path registerAppResource( server, { uri: resourceUri, name: add-app-to-server 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 }], } } )多个工具共用同一个 UI 时可以指向同一个resourceUri资源只注册一次。3.4 iframe 侧通信handler 注册顺序是关键UI 侧用App类建立和宿主的 postMessage 通道。所有 handler 必须在app.connect()之前注册这是最常见的翻车点import { App, PostMessageTransport, applyDocumentTheme, applyHostStyleVariables, applyHostFonts, } from modelcontextprotocol/ext-apps const app new App({ name: add-app-to-server UI, version: 1.0.0 }) app.ontoolinput (params) { renderLoading(params.arguments) } app.ontoolresult (result) { renderAppCard(result.structuredContent.data) } 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 () ({}) await app.connect(new PostMessageTransport())样式别硬编码用宿主注入的 CSS 变量主题切换才能跟着走.app-card { background: var(--color-background-secondary); color: var(--color-text-primary); font-family: var(--font-sans); border-radius: var(--border-radius-md); }3.5 可选app-only 轮询工具与 CSP面板上想实时刷新应用状态可以加一个模型不需要直接调、只给 UI 用的工具registerAppTool( server, poll-app-status, { description: 为 UI 轮询应用最新状态, _meta: { ui: { resourceUri, visibility: [app] } }, }, async () { const data await getLatestStatus() return { content: [{ type: text, text: JSON.stringify(data) }] } } )UI 里通过app.callServerTool(poll-app-status, {})调用。如果 UI 要加载外部字体或 API必须在资源注册时声明域名否则沙箱会拦_meta: { ui: { connectDomains: [api.example.com], resourceDomains: [cdn.example.com], frameDomains: [embed.example.com], }, }4. 验证请求用 basic-host 跑通 add-app-to-server 的 UI 渲染配置写完得实际跑一遍确认 iframe 真的渲染出来、回调真的触发。SDK 仓库自带basic-host示例是最省事的验证方式。先克隆 SDK 仓库注意用 npm 解析出的版本号拉对应分支git clone --branch v$(npm view modelcontextprotocol/ext-apps version) --depth 1 \ https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps然后两个终端并行。终端一构建并启动你的 servernpm run build npm run serve终端二启动 basic-hostcd /tmp/mcp-ext-apps/examples/basic-host npm install SERVERS[http://localhost:3001/mcp] npm run start打开http://localhost:8080你应该能看到宿主界面。SERVERS环境变量接收一个 JSON 数组填你的 server 地址默认是http://localhost:3001/mcp。验证清单逐项过一遍检查项预期结果不通过说明纯文本工具返回文本输出说明 content 回退被破坏App 工具iframe 内渲染出应用卡片资源注册或构建有问题ontoolinput触发并显示加载态handler 注册顺序错了ontoolresult卡片填入真实数据structuredContent 没传宿主样式主题、字体、颜色跟随没用 CSS 变量安全区内边距正确没处理 safeAreaInsets如果模型侧也要验证用 TaoToken 的模型对话入口发一条「把订单服务注册到测试服务器端口 8080」观察模型是否正确调用add-app-to-server、宿主是否把结果喂给 iframe。这一步通了整条链路就闭环了。5. 常见报错排查401、local proxy failed 与 choices 解析失败实际跑的时候报错基本集中在几个固定位置。下面按真实错误信息对照排查。401 Unauthorized。先分清是哪一层的 401。如果是模型调用返回 401检查 TaoToken 的 Key 是否复制完整、Base URL 是否写成https://taotoken.net/api别多加路径。如果是 MCP server 返回 401那是 server 自己的鉴权和模型层无关。两者混在一起排查会浪费很多时间。local proxy failed。这个通常出现在本地起 server 后宿主连不上。检查三件事server 是否真的监听在SERVERS里填的端口npm run serve有没有报错退出防火墙有没有拦本地回环。另外确认build先于serve执行过dist/mcp-app.html不存在时资源注册会失败表现上也可能连带出连接类错误。reading choices 报错。这是模型响应结构不符合预期时的典型症状多半是请求打到了不兼容的端点或者模型 ID 填错。回到 TaoToken 配置确认 Base URL 和模型 ID 匹配用模型对话入口单独发一条请求验证。如果单独请求正常、只有走工具调用时报错那问题在工具 schema 或 MCP 协议层不在模型。OAuth 相关报错。如果你接的是需要 OAuth 的 MCP servertoken 过期或 scope 不足都会报这个。检查授权是否完成、token 是否刷新。注意别把 OAuth 失败和 API Key 失败混为一谈前者是 server 侧授权后者是模型侧凭证。UI 渲染空白但无报错。八成是vite-plugin-singlefile没生效资源被拆成了多个文件沙箱里加载不到。检查vite.config.ts里插件是否引入、build:ui是否真的产出了单文件 HTML。另一个可能是 handler 注册在connect()之后回调根本没绑上。主题不跟随。检查是否用了var(--color-*)这类宿主变量硬编码颜色在深色主题下会很难看。onhostcontextchanged里要调用applyDocumentTheme和applyHostStyleVariables。排查顺序建议从外到内先确认模型层TaoToken 配置正常再确认 MCP server 能独立跑最后看 iframe 渲染。这样每层的问题不会互相掩盖。6. 把 add-app-to-server 沉淀成可复用 SDK 组件跑通一次之后真正省事的是把它抽成组件。我的做法是把「工具注册 资源注册 UI 构建」打包成一个函数传入应用元数据和渲染配置内部自动完成registerAppTool、registerAppResource和 URI 绑定。这样面板上再接第二个、第三个应用只需要改配置不用复制一遍样板代码。几个沉淀时的经验。第一resourceUri用命名空间前缀比如ui://tool-name/mcp-app.html避免多个工具撞车。第二structuredContent的字段定义单独抽成类型UI 和 server 共用改一处两边都跟着变。第三app-only 工具轮询、分页统一走visibility: [app]别让模型误调。第四CSP 域名白名单集中管理新增外部依赖时只改一个地方。如果你要长期跑这类编码和 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 的额度模型更适合持续调用接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Key 在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 管理。把 Key 和 Base URL 配好剩下的就是把这套 UI 增强模式复制到你的每一个服务器工具上——从add-app-to-server开始逐个加脸。