WebMCP

WebMCP

WebMCP Tools are host-page actions such as selecting an order, opening a record, or filling a form. They are different from backend Tools imported from Swagger/OpenAPI and executed by Agent4API.

The Embed loader does not register host Tools. It only discovers and bridges Tools that the host page has already registered and exposed to the Agent4API origin. If the browser or host does not support WebMCP, the integration is silently ignored. There is no backend fallback for a missing frontend Tool.

Host registration example

The exact registration API may track the browser's WebMCP implementation. Conceptually, the host registers before or alongside the Agent4API loader:

<script>
await document.modelContext.registerTool({
  name: 'select-order',
  description: 'Select an order in the host page',
  inputSchema: {
    type: 'object',
    properties: { id: { type: 'string' } },
    required: ['id']
  },
  execute: async ({ id }) => {
    document.querySelector('#selected-order').textContent = id
    return { selected: id }
  }
}, { exposedTo: ['https://agent.example.com'] })
</script>
<script src="https://agent.example.com/embed/PUBLIC_ID.js" async></script>

The loader creates its iframe with allow="tools". The Widget requests only Tools exposed from the exact parent origin. Host Tool names are presented to the Agent with a reserved web__ prefix so they cannot collide with backend Tools.

Execution boundary

1. The Agent selects an available web__... Tool through AG-UI.
2. The Widget validates the Tool name, arguments, size, and current discovery mapping.
3. The browser executes the original Tool in the host-page capability context.
4. The Widget serializes the result and sends it back to the Agent as a Tool message.
5. The Agent continues the same run and produces the response.

Discovery is bounded to 64 Tools. Tool schemas, arguments, and results are size-limited. Calls are serialized and time out after 30 seconds. Tool changes may trigger rediscovery.

If a Tool disappears between discovery and execution, the call fails as frontend_tool_unavailable. Agent4API does not execute a similarly named backend Tool, because doing so could turn a page action into an unrelated server-side side effect.

Browser and deployment requirements

• The browser must expose compatible document.modelContext discovery and execution capabilities.
• The host must register the Tool itself and expose it to the exact Agent4API origin.
• The iframe Permissions Policy must allow tools; the generated loader already sets it.
• Host and Agent4API Content Security Policies must permit the loader and frame.
• Cross-origin cookies are not shared with the iframe and are not used for host WebMCP authorization.

Use browser developer tools to inspect capability availability and registration errors. An unsupported browser should still provide normal embedded Agent chat without a warning.