教程2026-11-12 · 智涌AI

MCP Apps 入门:让你的 MCP 工具在 Claude 里出界面

MCP Apps 入门教程头图:终端里安装 ext-apps SDK,用 curl 依次看到 tools/list 返回 ui://quickstart/dice、resources/read 返回 text/html;profile=mcp-app、tools/call 返回 structuredContent,最后注册 add_item app tool 经审批加入 milk;标注约 50 行代码、单界面 64 个 app tool、45 秒响应时限

Anthropic 11 月 10 日(美国时间)把 Claude 的交互式连接器扩展成整套应用:Asana、Canva、Vercel 这些工具可以开在对话旁边甚至全屏,Claude 直接在里面改。背后用的是 MCP 的开放扩展 MCP Apps。你手上如果已经有一个 MCP 服务器,照 Claude 官方文档加 50 行左右代码,工具就能在对话里画出一个可以点的界面。这篇按官方 quickstart、app tools 和嵌入网站三份文档,把从零到能在 Claude 里点的路径拆开讲。

MCP App 就是带界面的工具结果

普通 MCP 工具返回文本,客户端把文本交给模型。MCP Apps 规范(当前稳定版 2026-01-26)多加了一层:工具声明一个 ui:// 开头的资源,资源内容是一段 HTML。支持这个扩展的宿主调用工具后,会去读这个资源,把 HTML 放进沙箱 iframe 里渲染,再通过消息把工具的输入和结果推给界面;界面也能反过来经宿主调用服务器上的其他工具。

这套东西 Claude 能用,别家宿主也能用。官方说法是按 MCP Apps 写的应用,任何支持该扩展的 AI 应用都能跑;SDK 里的 registerAppTool() 和 registerAppResource() 会替你生成各家宿主要的元数据。

服务器侧只多两样东西:一个 MIME 为 text/html;profile=mcp-app 的资源,和工具上指向它的 resourceUri。

前置条件

第一步:装 SDK,写一段 HTML

在 quickstart 项目目录里:

npm install @modelcontextprotocol/ext-apps@^1
npm ls --depth=0   # 应看到 ext-apps、sdk、zod 三个包

界面就是一段普通 HTML 字符串,关键是里面那段模块脚本:从 CDN 引入 SDK 的浏览器端 App,先挂好处理函数,最后 connect()。

const DICE_UI = 'ui://quickstart/dice';
// DICE_HTML 里的脚本核心:
import { App } from "https://unpkg.com/@modelcontextprotocol/ext-apps@1.7.5/dist/src/app-with-deps.js";
const app = new App({ name: "Dice View", version: "1.0.0" });
app.ontoolinput = ({ arguments: args }) => { /* 记住参数 */ };
app.ontoolresult = show;   // 宿主把工具结果推到这里,画骰子
$("again").onclick = async () =>
  show(await app.callServerTool({ name: "roll_dice", arguments: lastArgs }));
await app.connect();       // 和宿主握手

处理函数一定写在 connect() 之前,否则第一条工具输入和结果通知会漏掉。CDN 地址里的版本号要和你装的 ext-apps 版本一致。

第二步:把工具和资源连起来

把原来的 server.registerTool( 换成 registerAppTool(server,,加两处:

registerAppTool(server, 'roll_dice', {
  title: 'Roll dice',
  description: 'Roll `count` dice with `sides` sides each. Returns each roll and the total.',
  inputSchema: { sides: z.number().int().min(2).max(100), count: z.number().int().min(1).max(10).default(1) },
  _meta: { ui: { resourceUri: DICE_UI } },          // 指向界面资源
}, async ({ sides, count }) => {
  // ……算 rolls 和 total
  return {
    content: [{ type: 'text', text: `Rolled ${count}d${sides}: ...` }],  // 不渲染界面的客户端读这个
    structuredContent: { sides, count, rolls, total },                   // 界面读这个
  };
});

registerAppResource(server, 'Dice view', DICE_UI, { description: 'Interactive view for roll_dice' }, async () => ({
  contents: [{
    uri: DICE_UI,
    mimeType: RESOURCE_MIME_TYPE,   // 即 text/html;profile=mcp-app
    text: DICE_HTML,
    _meta: { ui: { csp: { resourceDomains: ['https://unpkg.com'] } } },
  }],
}));

最后那行 resourceDomains 是放行 CDN 脚本用的:沙箱默认只跑内联脚本和同源脚本,不写这行 App 引入会被拦。正式上线时官方建议把客户端脚本放自己的域名或直接打包进 HTML,只列那一个域名。

第三步:用 curl 验证服务器广播了界面

重启 node server.mjs,另开终端依次发三个请求(都带 Accept: application/json, text/event-stream):

curl -sS -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# 把 method 换成 resources/read,params 填 {"uri":"ui://quickstart/dice"}
# 再换成 tools/call,params 填 {"name":"roll_dice","arguments":{"sides":6,"count":4}}

按文档,三步分别应该看到:roll_dice 末尾带 _meta.ui.resourceUri(SDK 还会同时写一个旧的平铺键 ui/resourceUri);资源返回 mimeType 为 text/html;profile=mcp-app;工具结果同时有 content 文本和 structuredContent。

三条都对上,再部署到公网,在 Claude 网页或桌面端以自定义连接器加入,让它掷骰子。Claude Code 只把这个工具当文本工具调用,不渲染界面;claude.ai 是从 Anthropic 的服务器连你的 URL,localhost 连不到。

第四步:注册 app tool,让 Claude 改界面

前面那个界面只能人点。app tool 是注册在界面脚本里的工具,Claude 调用它就能改屏幕上的东西,比如购物清单里加一项「牛奶」。注意名字很像的两个函数:registerAppTool 在服务器上注册打开界面的工具;app.registerTool 在界面里注册 app tool。

app.registerTool("add_item", {
  title: "Add item",
  description: "Add an item to the shopping list that is open in this view.",
  inputSchema: z.object({ name: z.string().describe("The item to add") })
}, async ({ name }) => {
  // 往 #items 里插一条 li
  return { content: [{ type: "text", text: "Added " + name + "." }] };
});
await app.connect();

这种写法要 ext-apps 1.7.0 以上、zod 4.2 以上,而且得用打包工具。像 quickstart 那样从 CDN 加载 SDK 的,改用 onlisttools + oncalltool 自己写 JSON Schema,并在 new App() 第二个参数传 { tools: { listChanged: true } }。

测试方法:在网页版开一个合并了聊天和 Cowork 的新版对话(输入框还让你选 Chat 或 Cowork,说明账号没切过去),权限设为 Manual;第一条消息点名连接器、让它打开应用,第二条再让它加牛奶。Claude 会弹出 Add item 的审批,同意后清单里出现牛奶。

能力谁能用关键限制
对话内界面支持 MCP Apps 的宿主(侧栏、全屏要先查组织权限)脚本域名要写进 resourceDomains
app tool部分组织,且必须是远程连接器每个界面最多 64 个工具、定义合计 1 MiB、45 秒内返回、结果文本截到 10 万字符
嵌入网站目录里 Verified 连接器;自定义连接器仅部分组织Community 目录连接器和本地服务器一律拦截

第五步:嵌入自家网站

想把产品的编辑器或看板整个塞进界面,要做两边的配置。服务器侧,在 resources/read 返回的那项内容上声明域名:

{ "_meta": { "ui": { "csp": { "frameDomains": ["https://editor.example.com"] } } } }

网站侧,如果你的站限制了谁能嵌套它,Content-Security-Policy 的 frame-ancestors 要放行 https://claude.ai 和连接器的沙箱域名(claudemcpcontent.com 的子域)。沙箱域名不固定,每个对话都可能变,所以服务器上还要设 ui.domain,具体算法见官方「Set ui.domain for Claude」一节。

常见坑

做到哪一步算完成

这次 Claude 那边上了哪些应用、管理员怎么限制,见站内 Claude 交互式连接器快讯;想用 Python 写服务器,可以看 Python 写 MCP 服务器。

最后

先把 quickstart 的骰子跑通、三条 curl 全对,再决定要不要上 app tool 和嵌入网站,后两样都要看组织权限和连接器类型。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。