WebMCP Documentation

A Web Component that wraps an iframe and bridges its MCP tools, resources, and prompts to the parent page’s document.modelContext. Items from the iframe are namespaced with the element’s id to prevent collisions.

Installation

pnpm add @mcp-b/mcp-iframe @modelcontextprotocol/sdk

The iframe page must have @mcp-b/global (or any document.modelContext implementation) installed.

Minimal example

Usage

<mcp-iframe src="./child-app.html" id="my-app"></mcp-iframe>

<script type="module">
  import '@mcp-b/mcp-iframe';

  const el = document.querySelector('mcp-iframe');
  el.addEventListener('mcp-iframe-ready', (e) => {
    console.log('Exposed tools:', e.detail.tools);
    // e.g. ["my-app_calculate", "my-app_get_data"]
  });
</script>

Importing @mcp-b/mcp-iframe auto-registers the <mcp-iframe> custom element. No additional setup is required.

Attributes

Attribute	Type	Default	Description
`src`	`string`	—	URL of the iframe page.
`id`	`string`	`"iframe"`	Used as the tool name prefix. Sanitized to match `[a-zA-Z0-9_-]`.
`target-origin`	`string`	Inferred from `src`	Override the `postMessage` target origin. If omitted, the origin is extracted from the `src` URL.
`channel`	`string`	`"mcp-iframe"`	Channel ID for the underlying `IframeParentTransport`.
`call-timeout`	`number`	`30000`	Timeout in milliseconds for tool calls, resource reads, and prompt gets.
`prefix-separator`	`string`	`"_"`	Separator between the prefix and the item name. Must contain only `[a-zA-Z0-9_-]` characters.

Standard iframe attributes (sandbox, allow, width, height, loading, referrerpolicy, name, srcdoc, allowfullscreen, credentialless) are mirrored to the internal <iframe> element.

Events

Event	Detail type	Fired when
`mcp-iframe-ready`	`{ tools: string[], resources: string[], prompts: string[] }`	The element connects to the iframe’s MCP server and registers all items on the parent.
`mcp-iframe-error`	`{ error: unknown }`	Connection to the iframe’s MCP server fails.
`mcp-iframe-tools-changed`	`{ tools: string[], resources: string[], prompts: string[] }`	Items are refreshed via the `refresh()` method.

All tools, resources, and prompts arrays contain the prefixed names as registered on the parent.

Name prefixing

Tools and prompts from the iframe are registered on the parent as {id}{separator}{name}:

Iframe tool name	Element `id`	Separator	Parent tool name
`calculate`	`my-app`	`_` (default)	`my-app_calculate`
`get_data`	`billing`	`_`	`billing_get_data`
`help`	`assistant`	`-`	`assistant-help`

Prefixed names must match the MCP name pattern ^[a-zA-Z0-9_-]{1,128}$. Names that exceed 128 characters or contain invalid characters are skipped with a console error. Resource URIs are prefixed the same way: a resource config://settings in an iframe with id="my-app" becomes my-app_config://settings on the parent.

Properties

Property	Type	Description
`iframe`	`HTMLIFrameElement \| null`	The wrapped iframe element.
`client`	`Client \| null`	The MCP client connected to the iframe’s server.
`ready`	`boolean`	Whether the element is connected to the iframe’s MCP server.
`exposedTools`	`string[]`	Prefixed tool names registered on the parent.
`exposedResources`	`string[]`	Prefixed resource URIs registered on the parent.
`exposedPrompts`	`string[]`	Prefixed prompt names registered on the parent.
`mcpTools`	`Tool[]`	Raw tools from the iframe (without prefix).
`mcpResources`	`Resource[]`	Raw resources from the iframe (without prefix).
`mcpPrompts`	`Prompt[]`	Raw prompts from the iframe (without prefix).
`itemPrefix`	`string`	The computed prefix string (`{id}{separator}`).

Methods

Method	Returns	Description
`refresh()`	`Promise<void>`	Re-fetches all tools, resources, and prompts from the iframe, unregisters the old items, and registers the new ones. Fires `mcp-iframe-tools-changed` on completion.

Programmatic registration

To register the custom element with a different tag name:

import { registerMCPIframeElement } from '@mcp-b/mcp-iframe';

registerMCPIframeElement('my-mcp-frame');

If you import @mcp-b/mcp-iframe without calling registerMCPIframeElement, the element is auto-registered as <mcp-iframe> in browser environments.

Lifecycle

On connectedCallback, the element creates an internal <iframe> and mirrors attributes.
When the iframe fires its load event, the element creates an IframeParentTransport and an MCP Client, then connects.
On successful connection, tools, resources, and prompts are fetched from the iframe’s MCP server.
Each item is registered on the parent’s document.modelContext with the element’s prefix.
The mcp-iframe-ready event fires.
On disconnectedCallback, all registered items are unregistered and the client and transport are closed.

Changing src, srcdoc, target-origin, or channel while connected triggers a reconnection cycle.

Bridge tools across iframes for a step-by-step guide
@mcp-b/transports for the underlying IframeParentTransport and IframeChildTransport
Transports and bridges for the architectural context

Packages

WebMCP standard

Core runtime

React

Tooling

@mcp-b/mcp-iframe

Installation

Minimal example

Usage

Attributes

Events

Name prefixing

Properties

Methods

Programmatic registration

Lifecycle

​Installation

​Minimal example

​Usage

​Attributes

​Events

​Name prefixing

​Properties

​Methods

​Programmatic registration

​Lifecycle

​Related

Installation

Minimal example

Usage

Attributes

Events

Name prefixing

Properties

Methods

Programmatic registration

Lifecycle

Related