WebAgent ：基于 MCP 协议打造的智能应用“超级路由器”

本文由云软件体验技术团队李锦浩原创。

在 NextSDK 介绍文章里，我们聊了怎么用 @opentiny/next-sdk 给前端页面快速接入智能化能力——几行代码嵌进去，用户扫个二维码，手机上就能弹出一个 Remoter 对话窗口，直接用自然语言远程操控网页上的功能。效果是挺酷的，但不知道你有没有好奇过：这个对话窗口，到底是怎么跨设备、跨网络，把 AI 的指令传到网页上去执行的？

答案就是 WebAgent。你手机上弹出的 Remoter 对话窗口和网页之间，其实并没有直连——中间隔着企业网络、防火墙，直连根本不现实。WebAgent 就是站在中间的那个“MCP 转发中枢”：网页端通过 @opentiny/next-sdk 把自己的业务能力封装成 MCP 工具，注册到 WebAgent 上；Remoter 端连上 WebAgent 后，就能拿到这些工具的列表，再结合大模型做意图理解和决策。大模型决定调用哪个工具后，调用指令通过 MCP（Model Context Protocol）  协议发给 WebAgent，WebAgent 把它原样转发到对应的网页端去执行，再把结果送回来。简单说，WebAgent 就在 Remoter 和网页之间可靠地转发 MCP 消息。

WebAgent 是什么

简单说，WebAgent 是一个 MCP 协议的代理中转服务，现已在 GitHub 正式开源（opentiny/web-agent）。

还记得上一篇提到的场景吗？网页端用 @opentiny/next-sdk 把业务能力注册成 MCP 工具，手机上的 Remoter 对话窗口连上大模型来调用这些工具。但问题是——网页藏在企业内网里，手机在外网，两边根本连不上。WebAgent 做的事情，就是站在中间帮它们传话。

具体点说，WebAgent 的代理中转机制（核心实现在 @opentiny/agent 的 useProxyHandles()）维护了两个连接池——一边管着所有的 Client（被控端） ，一边管着所有的 Remoter（遥控端） 。整个过程是这样的：

1. Client 连上来，注册工具：网页端（或任何业务系统）通过 @opentiny/next-sdk 的 WebMcpClient 建立 MCP 连接，WebAgent 负责接收并保管它暴露的所有 MCP 工具。
2. Remoter 连上来，拿到工具列表：遥控端（比如 Remoter 对话窗口、Cursor、Dify 这样的 AI 应用）通过 MCP 协议连接到 WebAgent，指定要操控哪个 Client。WebAgent 会启动一个"代理 MCP Server"，把目标 Client 的工具列表原样透传给 Remoter。
3. 调用指令双向转发：当 Remoter 端的大模型决定调用某个工具时，指令不会直接发到网页——而是先发给 WebAgent, WebAgent 再把调用请求转发给对应 Client，Client 执行完再把结果沿原路返回。

换句话说，WebAgent 就像一个 MCP 协议层面的双向快递站：Client 往这儿发工具清单，Remoter 往这儿发调用指令，WebAgent 负责认准地址、原样投递，两边全程不需要知道对方在哪。

先看一下架构图，有个全局印象：

对照架构图，核心角色的分工非常清晰：

• 左侧 — 受控端（Client） ：网页应用、桌面应用、移动应用，通过 OpenTiny NEXT SDKs 连接到 WebAgent，把自己的业务能力注册为 MCP 工具。
• 中间 — Web Agent Server（代理中枢） ：负责维护两端的会话连接，做 MCP 消息的双向转发——工具列表、调用请求、执行结果，全部经它中转。
• 右侧 — 遥控端（Remoter） ：Agent Workflow（如 n8n、Dify）、IDE Copilot（如 Cursor、VSCode）、聊天对话框等 AI 应用，作为 MCP Client 连入 WebAgent，获取并调用远端业务工具。
• 上方 — 用户：通过自然语言与 AI 应用交互，AI 理解意图后自动转化为 MCP 工具调用。

深度阅读：如需了解更完整的生态与逆向设计思考，推荐阅读《一场 MCP 生态的变革——详解 OpenTiny NEXT 逆向思维的技术创新》。

核心亮点

1. 三端分离：【遥控-被控】代理架构

前面提到 WebAgent 维护了两个连接池——一边是所有的 Client（被控端），一边是所有的 Remoter（遥控端）。当 Remoter 连上来时，WebAgent 会自动帮它和指定的 Client 之间搭一条消息通道：Remoter 想调什么工具，WebAgent 原样转给 Client 去执行；执行完了，结果再原样送回来。

这套设计的好处很直接：Remoter 和 Client 之间完全不需要知道对方在哪。Client 在企业内网？Remoter 在手机上？没关系，只要它们各自能连上 WebAgent 就行。大模型负责想，Client 负责干，WebAgent 负责在中间递纸条——三个角色各管各的，互不耦合。

2. 标准 MCP 协议，开箱即用

WebAgent 没有另起炉灶造私有协议——它从头到尾走的都是 MCP 标准，完整覆盖了工具调用、资源读取、提示词管理等所有 MCP 规范定义的能力。

这意味着：你不需要为了接入 WebAgent 学任何新东西。Cursor、Dify、n8n、MCP Inspector……任何支持 MCP 协议的工具，直接连上来就能用。业务端也一样，用 SDK 把自己的功能注册成 MCP 工具就行，协议握手、会话管理这些事 WebAgent 全包了。

3. 两种传输方式，不挑网络环境

实际部署中网络环境千差万别，WebAgent 因此同时支持了两种传输方式：

• Streamable HTTP：标准的 HTTP 请求响应，适合防火墙严格、不允许长连接的环境。
• SSE 长连接：服务端主动推送消息，适合需要实时响应的场景。

两种方式对上层完全透明——不管用哪种接入，中间的转发逻辑都是同一套。部署到 Nginx 后面？加一行配置就能穿透。Serverless 环境？用 Streamable HTTP 模式就行。甚至可以直接拿 MCP Inspector 连上来联调，不需要任何额外配置。

5 分钟快速上手

将 WebAgent 运行在本地只需几条命令即可启动服务。唯一的前提要求是你的本地运行环境包含 Node.js >=22 及其配套工具链：

# 1. 获取项目代码
git clone https://github.com/opentiny/web-agent.git
cd web-agent

# 2. 安装项目依赖（请使用 pnpm 管理器）
pnpm install

# 3. 启动开发模式（支持热重载）
pnpm dev

生产部署用 pnpm build && pnpm start，也可以挂 PM2 跑守护进程。

服务跑起来之后，我们用一个最典型的场景把整个流程走一遍：假设你有一个网页应用，你想让 AI 能远程调用它上面的功能。整个过程分三步——接入、确认、调用。

第一步：把你的网页应用接入 WebAgent

在你的前端项目里，用 SDK 几行代码就能把业务功能注册到 WebAgent 上：

// 业务前端/微服务作为 Client 接入，NextSDK 将自动处理底层的双向连接
import { WebMcpClient } from '@opentiny/next-sdk';

// 创建连接，把你的应用挂到 WebAgent 上
const client = new WebMcpClient({ name: 'my-app-client', version: '1.0.0' });
const { sessionId } = await client.connect({
  agent: true,
  url: 'http://localhost:3000/api/v1/webmcp/mcp',
  sessionId: 'my-client-001', // 给你的应用起个名字
});
console.log('🔗 Client 已挂载到WebAgent，Session ID:', sessionId);

第二步：确认被控端已上线

应用接入之后，可以用 curl 看一眼——你的应用是不是已经在线了：

# 看看当前有哪些被控端（Client）连着
curl http://localhost:3000/api/v1/webmcp/list

如果返回结果里能看到 my-client-001，说明你的应用已经成功挂载到 WebAgent 上了。

第三步：用 AI 远程调用你的应用

确认连接没问题后，就可以从另一端（遥控端）接入大模型，让 AI 来调你的应用了：

import { AgentModelProvider } from '@opentiny/next-sdk';

const webAgent = new AgentModelProvider({
  llmConfig: {
    apiKey: 'your-llm-api-key',
    baseURL: 'https://api.deepseek.com/v1', // 换成你的大模型地址
    providerType: 'deepseek',
  },
  mcpServers: {
    // 指向第一步接入的那个应用
    'my-mcp-server': {
      type: 'streamableHttp',
      url: 'http://localhost:3000/api/v1/webmcp/mcp?sessionId=my-client-001',
    },
  },
});

// 大模型现在能看到 my-client-001 暴露的所有工具，直接用自然语言调用
const result = await webAgent.chat({
  model: 'deepseek-ai/DeepSeek-V3',
  messages: [
    { role: 'system', content: '你是一个智能助手，可以通过工具操作业务系统。' },
    { role: 'user', content: '帮我查一下 ID 为 1001 的业务数据' },
  ],
});
console.log('🤖 执行结果:', result.text);

遥控端连接成功后，你也可以用 curl 确认它已经在线：

# 看看有哪些遥控端（Remoter）在线
curl http://localhost:3000/api/v1/webmcp/remoter

典型落地场景

上面跑通的是最基础的链路。实际业务里，WebAgent + @opentiny/next-sdk 能玩出不少花样，这里举三个比较典型的方向：

1. 跨系统自动办事——拿出差申请举个例子

出过差的人都知道这个流程有多烦：先登 OA 看差旅政策，再开携程或同程查航班酒店，然后切到报销系统估费用，最后把截图和数据搬回申请表单——光是在几个系统之间来回切就得小半天。

接入 WebAgent 之后，员工只需要在工作台的对话框里说一句：“我要去深圳出差，下周二去周五回，帮我订符合标准的最早航班和离高新园最近的酒店，并提交出差申请”。剩下的事情 WebAgent 替你跑：

• 去 OA 系统查差旅政策和报销额度
• 去商旅平台挑符合标准的航班和酒店
• 把信息汇总填进审批表单，直接发起审批

原来要在好几个系统间来回跳的活儿，变成了一句话的事。（点击观看出差申请场景演示视频（官网首页视频））

2. 老系统低成本加上 AI 能力

很多企业的 ERP、工单系统里沉淀了几十上百张表单，全部重写不现实。但用 SDK 把关键操作包一层注册到 WebAgent 上，改动量其实很小。改完之后，操作员对着对话框说一句"审批流程转到第三级并抄送采购部主管"，AI 理解意图，WebAgent 把指令转给对应系统去执行——不用培训员工记菜单在哪、按钮点哪个，说句话就能办。

3. 微前端集群的统一调度入口

如果你的业务拆成了很多微前端子应用，每个子应用作为 Client 挂到 WebAgent 上之后，大模型就能一次请求同时操作多个子应用——比如一边从销售看板拉数据，一边往通知服务发消息。以前跨子应用的联动要写一堆胶水代码，现在 WebAgent 当中间人，子应用之间不需要互相知道对方的存在，通过 WebAgent 转发就能协作。

未来展望与共建邀请

目前开源出来的 WebAgent，核心的 MCP 代理转发能力已经跑通了。但说实话，这只是我们想做的事情的一小部分——既然 WebAgent 已经站在了 AI 和业务系统之间，很多事情顺着这个位置自然就能往下延伸：

• LLM 代理中转：现在遥控端要自己配大模型的 API Key 和地址，如果团队里十几个应用都要接，每个都单独管一套密钥和配额，运维起来很头疼。我们在考虑让 WebAgent 直接内置大模型的代理能力——业务端只管发请求，模型选择、密钥管理、限流熔断这些事情统一在 WebAgent 这一层搞定。
• MCP 工具的统一管理：当接入的 Client 越来越多、注册的工具越来越杂，"谁能调什么"就变成了一个实际问题。我们计划加上工具的权限控制、版本管理和可视化的管理后台，让管理员能清楚地看到当前有哪些工具在线、谁在用、调用情况怎么样。
• Agent 托管：再往后想一步——如果 WebAgent 不只是转发消息，而是能直接托管一个完整的 Agent 运行时呢？业务方定义好 Agent 的 Prompt、工具集和工作流，往 WebAgent 上一扔，它就能自己跑起来。这样业务团队连 Agent 的运行环境都不用操心了。

我们将继续打磨和探索 WebAgent 的更多可能性。

如果你正站在业务智能改造的关键节点，或被各路模型杂乱不齐的长链接交互卡住了业务节奏，我们非常诚挚地邀请你试用并打磨：

🚀 立即访问体验 WebAgent：
👉 GitHub 仓库：https://github.com/opentiny/web-agent （在此邀请试用并提交 Issue 反馈，也极其感谢能为这群满怀赤诚的开源工程师点上一颗 🌟 Star）
👉 WebAgent 文档：https://docs.opentiny.design/web-agent/guide/getting-started.html
👉 OpenTiny 官网体验：https://opentiny.design/
👉 关于我们：https://opentiny.design/opentiny-design/about