WebMCP详解：为浏览器中的AI智能体提供工具，而非依赖猜测。

让人工智能代理在网站上预订航班，看看会发生什么。它会打开页面并开始尝试操作。哪个元素是日期选择器？哪个下拉菜单用于选择目的地？哪个按钮因为被模态框遮挡而需要点击两次？有时代理能够成功完成操作，有时则会点击错误的位置，往字段中输入错误内容，或者因为在模型训练后页面布局发生变化而在结账环节卡住。

这就是如今大多数基于浏览器的智能代理的运作方式。它们会抓取DOM结构，通过标签和位置判断每个元素的功能，然后模拟人类会进行的点击和按键操作。这种技术被称为“驱动机制”，在演示中表现良好，但在实际应用中却容易出问题。只要更改一个CSS类或移动一个按钮，昨天还能正常工作的代理就会出故障。

WebMCP正是为了解决这一问题而出现的。如果你熟悉后端的模型上下文协议（MCP），其理念其实很简单：将工具的概念引入浏览器，使其存在于你构建的页面中。

为何仅依赖DOM不够

目前，智能体访问服务有两种途径：

• 后端集成。服务通过MCP服务器、OpenAPI或某些专有API在AI平台上注册工具，AI直接与服务器通信，无需接触浏览器。
• 浏览器操作。智能体像人类一样打开页面，尝试判断需要点击或填写哪些元素。

这种操作方式成本高昂且容易出错。每个步骤都可能被误读，尤其是在现代单页应用这种结构复杂、层次众多的界面中。

WebMCP增加了一种第三种方式，既不是后端集成，也不是盲目点击。网站本身会明确说明其功能。开发者会直接说明结账功能的作用、所需输入以及返回结果，而非让智能体去猜测结账按钮的功能。

什么是WebMCP

WebMCP是由W3C的Web机器学习社区小组提出的一种网络标准。该规范定义了JavaScript API以及HTML表单元素的注释，这样智能体就能无需猜测就能使用页面的功能。

将其与后端MCP相比，实现了WebMCP的页面表现得就像一个MCP服务器，其工具以客户端脚本的形式运行。通常情况下需要单独搭建服务器来提供功能，而现在则可以直接从页面上已运行的JavaScript中注册相应功能。

这一设计由三部分组成：

• 发现机制：一种让页面向智能体注册如 checkout 或 search_products 等工具的标准方式。
• JSON Schema：对预期输入与输出的明确定义，有助于减少错误生成与误解。
• 状态信息：页面当前上下文的共享视图，使智能体能够知晓当前可执行的操作。

还有一个细节：这些工具仍会在页面上以可见形式运行。当智能体调用 add_to_cart 工具时，结果会显示在用户界面中，而非默默完成操作。这对建立信任很重要，因为用户能够看到为自己完成的操作，且你设计的体验不会被绕过。

在站点上注册 WebMCP

将其添加到现有网站中并非重新构建，而是在已运行的后端之上增加一层额外的通信层。操作步骤如下：

1. 启用该功能环境。由于该标准仍处于提案阶段，可手动开启以便进行测试。在 Chrome 中打开 chrome://flags/#enable-webmcp-testing，将其设置为“已启用”然后重启浏览器。若希望更接近实际生产环境，可注册从 Chrome 149 开始提供的 WebMCP 原生功能试用版，这样真实访问者无需调整浏览器设置即可使用该功能。

2. 选择值得展示的工具。这一步很容易被忽视。不要仅仅因为可以就展示所有功能。思考一下人们真正希望智能体帮忙完成哪些操作，通常是那些有明确目的的操作：搜索、筛选、提交表单、结账等。避免在一页上展示数十种工具，因为每一种已注册的工具都会占用上下文窗口空间，而过长的菜单会让智能体难以做出选择。

3. 选择命令式或声明式 API。命令式 API 通过 registerTool 函数使用纯 JavaScript 注册工具，适用于状态管理、导航或操作链等较为复杂的逻辑。声明式 API 则直接在标准的 HTML <form> 元素上添加注解，系统会自动为该表单生成对应的工具，非常适合简单的表单驱动场景。React 和 Angular 项目都提供了框架原生的相关选项：React 提供 usewebmcp 包，其 useWebMCP 钩子可将工具的生命周期与组件的挂载和卸载绑定在一起；Angular 则提供了实验性支持，能够将 Signal Forms 转换为工具。

4. 使inputSchema更加详细。这决定了智能体对工具的理解程度。请用通俗的自然语言撰写description，避免使用内部缩写，并为每个属性指定其类型。对于值范围固定的情况，使用enum，这样可以降低智能体发送无效数据的可能性。

5. 设置与实际风险相匹配的annotations。每个工具都需要一个准确的标签：

• 对于仅用于读取且不修改任何内容的工具，设置readOnlyHint: true。
• 对于会产生实际影响的操作，应设置consequentialHint: true，以便先提示用户确认。
• 当输出内容包含来自其他用户的评论或意见等可能隐藏指令的信息时，设置untrustedContentHint: true。

6. 将 execute 函数连接到现有的端点。 可以直接使用 fetch() 调用已有的 API 路由，Laravel 路由同样适用。无需额外的 WebMCP 后端，只需构建一个前端桥梁，连接那些已在生产环境中经过验证的业务逻辑即可。

7. 进行测试。 安装名为 Model Context Tool Inspector 的 Chrome 扩展程序（可在 Chrome Web Store 获取），加载你的页面，查看有哪些工具被注册。你还可以通过该扩展与客服人员沟通，确认你的工具是否被正确调用，其结构信息是否清晰可读。

8. 将其视为渐进式增强方案。 由于浏览器对 WebMCP 的支持有限，对于那些浏览器不支持该技术的访问者，普通的按钮点击功能仍需正常工作。新方案只是增加了一种路径，并不会替代原有的功能。

示例：订单状态查询工具

以基于Laravel构建的在线商店为例，它拥有订单状态页面。正常流程是用户登录后进入“我的订单”，选择日期范围，即可查看带有配送状态的订单列表。而使用actuation的客服人员则必须找到相应的下拉菜单和提交按钮，然后从原始HTML中解析出结果表格，一旦标记结构发生变化，这种解析方式就会失效。

借助WebMCP，只需一个工具就能封装现有的接口：

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Look up orders within a given timeframe. Returns order number, shipping status, and current location.',
  inputSchema: {
    type: 'object',
    properties: {
      timeframe: {
        type: 'string',
        enum: ['today', 'yesterday', 'last_7_days', 'last_30_days', 'last_6_months'],
        description: 'Timeframe for the order lookup.'
      }
    },
    required: ['timeframe']
  },
  annotations: {
    readOnlyHint: true,
    consequentialHint: false,
    untrustedContentHint: false
  },
  execute: async ({ timeframe }) => {
    const response = await fetch(`/api/orders/status?range=${timeframe}`, {
      headers: { 'Accept': 'application/json' }
    });
    const data = await response.json();
    return JSON.stringify(data);
  }
});

有三个要点值得注意。inputSchema能让代理无需猜测格式，因为它知道timeframe接受哪些值。readOnlyHint: true注解表明该工具不会产生副作用，因此无需确认。而execute只是调用现有的Laravel路由，无需重新构建任何内容。

结账流程则更为敏感，因为涉及资金流转和订单创建，因此需要不同的信号来处理：

await document.modelContext.registerTool({
  name: 'checkout_cart',
  description: 'Completes checkout for the currently logged-in user\'s cart.',
  inputSchema: {
    type: 'object',
    properties: {
      paymentMethod: { type: 'string', description: 'Payment method selected by the user' }
    },
    required: ['paymentMethod']
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false
  },
  execute: async ({ paymentMethod }) => {
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ payment_method: paymentMethod })
    });
    return await response.text();
  }
});

当设置 consequentialHint: true 时，浏览器或客户端会在执行操作前显示确认对话框。即便客户端点击了按钮，最终决定权仍在于用户。

要列出页面上注册的工具：

const tools = await document.modelContext.getTools();
console.log(tools);

如需手动触发以进行测试：

const [tool] = await document.modelContext.getTools();
const result = await document.modelContext.executeTool(tool, '{"timeframe": "last_7_days"}');

完整的往返流程

以下是当你与使用 get_order_status 工具的客服人员聊天时的操作顺序。

1. 你在客服人员打开店铺页面的情况下，用通俗的语言输入类似“查找我上周的订单”这样的内容。
2. 客服人员通过调用页面上的 getTools() 方法来检索可用工具。
3. 页面会返回包含各工具结构信息的列表，其中包括带有描述和输入格式的 get_order_status 工具。
4. 客服人员根据描述匹配你的需求，清晰的描述有助于其立即选出合适的工具。
5. 客服人员使用从对话中提取的参数（如 {timeframe: 'last_7_days'}）来调用 executeTool() 方法。

该页面的execute函数通过fetch()调用相同的Laravel接口，就像用户点击按钮一样。

后端以JSON格式返回响应，工具再将该数据传递给代理。

代理会将结果用自然语言表达并展示出来，同时整个过程都会显示在页面界面中。

为什么这比传统触发方式更好？

• 对上下文的要求更低。代理只需读取简洁的架构描述，而非数千行的标记代码，因此响应速度更快，成本也更低。
• 结果更加稳定。工具会直接调用实际的函数，因此更改按钮颜色或移动元素不会破坏功能。
• 用户仍能掌控全局。标有consequentialHint: true的高风险操作仍需用户确认，因此代理无法擅自执行。

更易于审计。所有交互都会通过专门的工具完成，因此你可以准确记录客服为用户做了什么操作，而仅靠手动点击则很难做到这一点。

安全性

由于这些工具运行在用户的页面上，其安全性比通常独立运行在专用服务器上的后端MCP更高。该规范提供了多项保护措施：

• 源隔离。WebMCP仅在源隔离的文档中运行。如果页面通过Origin-Agent-Cluster: ?0头部等信息启用了document.domain，WebMCP就会停止工作。
• 权限策略。工具的注册受tools策略控制，默认值为self，因此跨域iframe无法注册工具，除非你使用allow="tools"明确允许。

来源暴露设置。若要让某个工具可从其他来源访问，需将该来源列入exposedTo选项中。默认情况下没有任何内容会被自动暴露。

三种注释提示。readOnlyHint、consequentialHint和untrustedContentHint并非单纯的标签，它们用于指示智能体是否可以无需确认即可运行该工具，或者因为其输出包含用户评论等不可信内容而需谨慎处理，这类内容可能存在注入风险。

需要说明的一点是：标签页间的隔离功能仍在完善中。如果智能体需要在两个标签页之间操作，目前并没有机制能够防止敏感信息从其中一个标签页泄露到另一个标签页。对于银行等对安全性要求极高的场景，在依赖此功能之前应先关注这一问题。

浏览器支持现状

截至2026年中期，这项功能仍处于早期阶段：

• W3C Web机器学习社区组于2025年9月正式接受了该规范。
• Chrome从149版本开始提供测试版本，而Chrome和Edge的正式支持预计在2026年下半年推出。
• 对于本地测试，无需加入测试计划即可通过chrome://flags/#enable-webmcp-testing标志进行操作。
• Model Context Tool Inspector扩展可以显示页面注册了哪些工具，并能模拟智能体之间的对话。

该提案仍可能发生变化，因此不要将其视为即将投入生产的功能。应采用渐进式增强策略：在浏览器支持WebMCP的情况下，智能体能获得更精准的体验；在不支持的情况下，则沿用原有的手动操作流程。

当前限制

• 不支持无头浏览。该 API 适用于有人参与的本地浏览器操作流程，而非无人监管的自动化场景。
• 复杂界面会增加负担。那些具有复杂状态管理的应用很可能需要重构，以便相关工具能够反映应用的真实状态。
• 发现工具需手动访问。客户端只有通过访问页面才能知晓某个站点存在哪些工具，目前还不存在类似站点地图那样的全局工具索引。
• 暂不支持资源与提示功能。完整 MCP 中的另外两种基础功能尚未被引入 WebMCP。如果智能体需要读取文档或从其他地方获取结构化数据，仍然需要单独的 MCP 服务器。

从何处开始

WebMCP是对后端MCP的补充而非替代。那些必须运行在服务器上的数据和逻辑仍应使用后端MCP，而WebMCP则更适合前端交互层：复杂的表单、多步骤导航以及与屏幕上显示的UI状态相关的操作。

安全的入门方式：

• 开启本地模式并注册一个简单的工具，最好是只读工具，比如产品搜索功能。
• 从一开始就正确使用annotations功能。不要推迟设置readOnlyHint和consequentialHint，因为它们是决定代理在使用你的工具时能被信任到何种程度的安全基础。
• 关注GitHub上Web机器学习社区组的仓库，因为社区的讨论会不断推动规范的完善。

WebMCP虽然尚未成熟，但其发展方向十分明确。网络领域正在形成一种用于与智能体通信的标准化语言，开发者与智能体之间也有明确的契约，从而取代了以往依赖DOM猜测的方式。对于那些熟悉后端MCP相关工具和架构的人来说，这种转变会显得很熟悉——因为契约现在就存在于浏览器中。