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

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。
前置条件
- 一个能跑的 Node.js MCP 服务器。官方 quickstart 接着「Build your first MCP server for Claude」那篇的
server.mjs(Streamable HTTP,/mcp路径,一个掷骰子工具roll_dice)往下写。没有的话先看站内 MCP 是什么、怎么配。 - SDK 版本对齐:
@modelcontextprotocol/ext-apps的 1.x 配@modelcontextprotocol/sdk1.x。官方页面按 ext-apps 1.7.5、sdk 1.30.1、zod 4.6.5 校验过。 - 要在 Claude 里看到界面,得有公网 HTTPS 地址(或开发时用隧道),再以自定义连接器的方式加进 Claude。
第一步:装 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 要到你下一条消息才拿到它的工具。先让它打开,再提要求。
- 把 zod 的对象形状直接传给
app.registerTool。服务器工具接受{ name: z.string() }这种形状,界面里不行,得传z.object(...)。传错了界面回tools/list报错,同一界面的其他工具也一起看不见。 - 报
Client does not support tool capability。connect()之后才第一次注册工具,或者用了 handler 写法却没在构造函数里声明tools能力。 - 嵌入的站点里弹窗、新标签打不开。
window.open()和target="_blank"在沙箱里不生效,改用官方文档给的ui/open-link,对话框做进页面里。 - 改了工具描述,用户又被问一遍。用户点过「Always allow」后,名称、标题、描述或输入结构一变,Claude 可能重新要求审批。会变的值(比如当前文件名)放进返回结果,别写进定义。
做到哪一步算完成
- 三条
curl分别看到resourceUri、text/html;profile=mcp-app和structuredContent。 - 服务器挂到公网并加了认证(官方特别提醒:quickstart 原样上线谁都能调你的工具),在 Claude 里能看到骰子界面,点「Roll again」能重掷。
- 组织有 app tool 权限的话,Claude 能通过审批弹窗往界面里加内容;没有权限时界面其余部分照常工作。
这次 Claude 那边上了哪些应用、管理员怎么限制,见站内 Claude 交互式连接器快讯;想用 Python 写服务器,可以看 Python 写 MCP 服务器。
最后
先把 quickstart 的骰子跑通、三条 curl 全对,再决定要不要上 app tool 和嵌入网站,后两样都要看组织权限和连接器类型。