从"对话"到"界面"：MCP Apps 的诞生
1.1 当前 AI 交互的痛点
相信你已经深有体会：今天的 AI 助手，无论是 Claude、ChatGPT 还是基于大模型的各种 Agent，核心交互方式都是文本对话。你问一句，AI 答一段。需要数据分析？AI 给你生成一段 Markdown 表格。需要可视化？它最多画一张静态的 ASCII 图表。

这种模式在简单场景下够用，但一旦涉及复杂操作——筛选数据、调整参数、实时预览——"对话"就成了效率的瓶颈。

开发者们很早就意识到这个问题。既然 MCP 协议已经让 AI 能够调用外部工具，为什么不进一步让工具返回的不仅是文本，而是一套完整的交互界面呢？

1.2 MCP Apps 是什么
MCP Apps（仓库名 ext-apps）是 MCP 协议的官方扩展，由 Anthropic 于 2026 年 1 月 26 日正式发布。它的核心能力可以用一句话概括：

MCP 工具可以返回交互式 UI，直接嵌在 Claude、ChatGPT 的对话窗口里。

具体来说，对话窗口中会嵌入一个真实的 iframe，里面跑的是由 MCP Server 提供的前端代码。按钮能点、图表能拖、表单能填，数据在前后端之间双向流动。

最关键的是它的渐进增强设计哲学：支持渲染的客户端显示交互界面；不支持的客户端（比如终端工具）照样收到纯文本，不会破坏任何现有功能。

1.3 三方架构模型
MCP Apps 的架构由三个核心角色组成：

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Server │ │ Host │ │ View │
│ │ │ │ │ │
│ • 注册工具 │◄────┤ • Claude Desktop │◄────┤ • iframe 沙箱 │
│ • 暴露资源 │ │ • ChatGPT │ │ • 前端渲染 │
│ • UI 资源声明 │ │ • VS Code │ │ • 用户交互 │
│ │ │ • 数据中转 │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
▲ │ │
└───────────────────────┴────────────────────────┘
所有通信经 Host 中转
角色 职责 实例
MCP Server 注册工具时在 _meta.ui.resourceUri 里指向 ui:// 资源 Grocery Inventory API
Host 创建 iframe、负责数据搬运、通信中转 Claude Desktop、ChatGPT、VS Code Insiders
View 跑在 iframe 沙箱里的前端代码，渲染界面，反向调用 Server 工具 仪表盘、地图、图表组件
一个关键的架构约束：View 不能直接跟 MCP Server 通信，所有通信必须经过 Host 中转。这确保了安全性和可审计性。

1.4 View 的七种能力
View 并不是简单的静态页面，它拥有一整套与 MCP Server 和 Host 交互的能力：

能力 作用
tools/call 调用 Server 的工具
resources/read 读取 Server 的资源
ui/message 往对话里插入消息
ui/update-model-context 静默更新模型上下文（核心能力，用户在 UI 上的操作实时反馈给 LLM）
ui/open-link 打开外部链接
ui/request-display-mode 切换显示模式：inline / fullscreen / pip
visibility 工具可见性控制，[“app”] 标记仅 View 可调
其中，ui/update-model-context 是实现 Human-in-the-Loop 的核心机制。用户在 UI 上的每一次操作——点了哪个按钮、改了哪个筛选条件、选了哪个时间范围——都可以通过这条通道实时反馈给大模型，形成一个用户操作 → 更新上下文 → LLM 重新决策 → 刷新界面的完整闭环。

1.5 MCP Apps 的价值
MCP Apps 的出现，本质上是在回答一个 AI 产品设计的核心命题：如何让 AI 干活，同时在关键节点上让人确认？

传统的 Agent 模式是"AI 决定 → 执行 → 告诉你结果"，用户全程被动。而 MCP Apps 开启了一种新的范式：“AI 决定调什么工具 → 给你一个交互界面 → 你在界面上确认/调整 → 结果实时反馈给 AI 继续处理”。

这不仅仅是"更好看的输出"，而是人机协作范式的升级。

二、OpenClaw.NET 率先响应：PR #168 的意义
2.1 .NET 生态的"第一个"
MCP Apps 协议发布后，各路 SDK 和框架开始跟进。但在 .NET 生态中，率先给出完整答案的是 OpenClaw.NET。

PR #168（作者：geffzhang，已合并至 main 分支）为 OpenClaw.NET 增加了原生的 MCP App 支持。这个 PR 的规模充分体现了其工程完整度：

+4,012 行代码，22 个文件变更
43 个全新单元测试
2,308 个现有测试全部通过，零破坏性变更
中英双语文档
这个数字很有意思：4,000+ 行新代码，却没有任何破坏性变更。这说明 OpenClaw.NET 的架构设计从一开始就为扩展预留了足够的空间。

2.2 为什么是"第三层"架构
要理解 OpenClaw.NET 的 MCP App 支持，我们需要先看看它已有的 MCP 相关架构。

在 PR #168 之前，OpenClaw.NET 已经在两个维度上支持了 MCP：

层级 模块 方向 用途
MCP Server OpenClaw.Gateway/Mcp 对外暴露 把 OpenClaw 自身作为 MCP Server，对外提供工具
MCP Client OpenClaw.Agent/Plugins 对内消费 连接外部 MCP Server，消费第三方工具
MCP App (新增) OpenClaw.McpApp 托管管理 发现、管理、托管第三方 MCP 应用
前两层解决的是"如何连接"的问题：作为 Server 被连，或作为 Client 去连别人。而新增的第三层 OpenClaw.McpApp 解决的是一个更上层的问题：如何在一个统一的框架内，大规模地管理、运行、协调多个 MCP 应用？

这不是简单的"再加一个客户端"，而是一个完整的应用生命周期管理层。

三、三层架构的完整图景
让我们把三个层级放在一起，看看 OpenClaw.NET 的 MCP 架构全景：

┌─────────────────────────────────────────────────────────────────────┐
│ OpenClaw.NET 生态 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ OpenClaw.Gateway │ ◄── 外部 MCP Client（如 Claude Desktop） │
│ │ (MCP Server 层) │ 通过 MCP 协议连接 │
│ │ │ │
│ │ 暴露 OpenClaw 工具 │ │
│ │ 作为标准 MCP Server │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ ┌──────────────────────────────────┐ │
│ │ OpenClaw.McpApp │ │ OpenClaw.Agent/Plugins │ │
│ │ (MCP App 托管层) │ │ (MCP Client 层) │ │
│ │ │ │ │ │
│ │ • 发现 MCP App │ │ • 连接到外部 MCP Server │ │
│ │ • 管理生命周期 │ │ • 消费外部工具 │ │
│ │ • 维护连接状态 │ │ • 集成到 Agent 工作流 │ │
│ │ • 桥接为 ITool │◄────┤ │ │
│ │ │ │ 方向：Client → 外部 Server │ │
│ │ 方向：Host → 托管 App│ │ │ │
│ └──────────┬──────────┘ └──────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 第三方 MCP App 生态 │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │库存管理 │ │系统监控 │ │地图服务 │ │PDF 查看器 │ │ │
│ │ │(grocery) │ │(system) │ │(map) │ │(pdf) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
这个架构的精妙之处在于方向性的清晰划分：

MCP Server 层（向外）：OpenClaw 说"我的工具在这里，谁来连我"
MCP Client 层（向内）：OpenClaw 说"我去看外面有什么工具可以用"
MCP App 层（托管）：OpenClaw 说"我来管理和运行这些完整的 MCP 应用"
四、核心组件深度解析
OpenClaw.McpApp 项目包含 7 个核心组件，它们共同构成了一个完整的 MCP 应用托管平台。让我们逐一拆解。

4.1 McpAppManifest — 应用的"身份证"
每个 MCP App 都需要一个 openclaw.mcpapp.json 清单文件，它定义了应用的基本信息、传输方式和能力声明。

{
“id”: “grocery-inventory”,
“name”: “Grocery Inventory Manager”,
“description”: “Multi-store inventory management system”,
“version”: “1.0.0”,
“transport”: “http”,
“url”: “https://localhost:5001/mcp”,
“hasUi”: true,
“uiResourceUri”: “ui://grocery/store-dashboard.html”,
“toolNamePrefix”: “grocery.”,
“capabilities”: [“tools”, “resources”, “prompts”, “completions”]
}
这个设计体现了几个关键考量：

transport 支持 stdio（子进程）、http（远程端点）、inprocess（进程内），覆盖了从本地工具到远程服务的全部场景
toolNamePrefix 避免了命名冲突——grocery.inventory.search 和 sales.inventory.search 可以共存
hasUi + uiResourceUri 声明了交互式 UI 的能力和资源地址
capabilities 显式声明支持的功能，便于 Host 做能力协商
4.2 McpAppInstallState — 六阶段生命周期
每个 MCP App 从被发现到最终运行，会经历一个严格定义的状态机：

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Discovered │───►│ Validated │───►│ Loaded │
│ (被发现) │ │ (已验证) │ │ (已加载) │
└─────────────┘ └──────┬──────┘ └──────┬──────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Disabled │ │ Running │
│ (禁用) │ │ (运行中) │
└─────────────┘ └──────┬──────┘
│
┌────────────────────┘
▼
┌─────────────┐ ┌─────────────┐
│ Stopped │◄─────│ Failed │
│ (已停止) │ │ (失败) │
└─────────────┘ └─────────────┘
状态 含义 转换条件
Discovered 清单文件被扫描发现 自动扫描触发
Validated 清单格式验证通过 JSON Schema 校验
Disabled 被配置显式禁用 Enabled: false
Loaded 应用配置已加载 验证通过后自动进入
Running 连接已建立，工具可用 McpAppServer 成功连接
Stopped 已停止运行 框架关闭或手动停止
Failed 连接或运行出错 超时、网络错误、协议错误
这个状态机的价值在于可观测性和可控性。在生产环境中，你可以精确知道每个 MCP App 处于什么状态，出了什么问题，而不是面对一个"连不上"的黑盒。

4.3 McpAppDiscovery — 智能发现机制
McpAppDiscovery 是一个递归清单扫描器，负责在指定路径下自动发现 MCP App：

// Discovery 配置示例
{
“DiscoveryPaths”: [“./mcpapps”], // 扫描哪些目录
“Allow”: [“grocery-", "monitor”], // 白名单，支持 glob 模式
“Deny”: [“-test", "deprecated-”] // 黑名单，优先于 Allow
}
扫描器会递归搜索 **/openclaw.mcpapp.json 文件，反序列化后进行验证，再通过 allow/deny/glob 过滤规则筛选。这套机制让 MCP App 的部署变得极其简单——把应用目录扔进去，框架自己找到并加载。

4.4 McpAppServer — 连接的生命周期管理
McpAppServer 负责管理单个 MCP App 的连接生命周期。它的核心职责包括：

根据 transport 类型选择连接方式（stdio 子进程 / HTTP 端点 / 进程内）
建立 MCP 协议连接
枚举可用的 tools、resources、prompts
生成 IMcpAppInfoProvider 供上层使用
支持幂等重连——连接断开时自动恢复
// 伪代码示意
class McpAppServer
{
// 幂等启动：如果已经在运行，直接返回
async Task StartAsync()
{
if (State == ConnectionState.Connected) return;

    // 根据 transport 创建连接
    var transport = transportType switch
    {
        "stdio" => new StdioTransport(executablePath),
        "http" => new HttpTransport(endpointUrl),
        "inprocess" => new InProcessTransport(instance),
        _ => throw new NotSupportedException()
    };
    
    // 连接、握手、枚举能力
    await transport.ConnectAsync();
    var capabilities = await EnumerateCapabilitiesAsync();
    
    State = ConnectionState.Connected;
}

}
4.5 McpAppNativeTool — 无缝桥接到 ITool
这是整个架构中最关键的"胶水层"。McpAppNativeTool 将远程 MCP App 提供的工具，桥接到 OpenClaw 内部的 ITool 接口：

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP App │ │ McpAppNativeTool │ │ OpenClaw Agent │
│ (远程) │◄───────►│ (桥接层) │◄───────►│ (ITool 接口) │
│ │ MCP │ │ ITool │ │
│ • search │ 协议 │ 封装远程调用 │ 协议 │ Agent 无感调用 │
│ • update │ │ 统一错误处理 │ │ │
│ • delete │ │ 参数/结果映射 │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
对于 Agent 来说，调用一个 MCP App 的工具和调用一个原生插件的工具没有任何区别。Agent 不需要知道 grocery.inventory.search 是来自一个本地函数还是一个远程 HTTP 服务——这一切都被桥接层透明地处理了。

4.6 McpAppRegistry — 集中注册表
McpAppRegistry 是整个 MCP App 子系统的"指挥中心"：

管理全部 App 的发现、连接和追踪
协调 McpAppDiscovery 和 McpAppServer
提供查询接口：按 ID 查找、按能力过滤、按状态筛选
处理启动时的批量连接和关闭时的优雅清理
4.7 McpAppServiceExtensions — 极简的 DI 注册
最后，McpAppServiceExtensions 提供了一行代码完成所有注册的体验：

// Program.cs
builder.Services.AddOpenClawMcpApps(builder.Configuration.GetSection(“McpApps”));
框架内部会依次注册 Discovery → Registry → Server Factory → NativeTool Factory，完全不需要手动干预。

五、实战：从配置到运行
5.1 Gateway 配置
在 appsettings.json 中新增 McpApps 配置节：

{
“McpApps”: {
“Enabled”: true,
“DiscoveryPaths”: [“./mcpapps”],
“Allow”: [“*”],
“Deny”: [],
“Entries”: {
“grocery-inventory”: {
“Enabled”: true,
“Url”: “https://localhost:5001/mcp”,
“ToolNamePrefix”: “grocery.”,
“StartupTimeoutSeconds”: 15
}
}
}
}
配置分为两部分：

全局配置：Enabled 总开关、DiscoveryPaths 扫描路径、Allow/Deny 过滤规则
应用配置：Entries 下每个 MCP App 的具体连接参数