WebMCP Documentation

The <mcp-iframe> custom element wraps an iframe and automatically exposes its tools, resources, and prompts to the parent page’s navigator.modelContext.

Installation

npm install @mcp-b/mcp-iframe @modelcontextprotocol/sdk

Requires @mcp-b/global polyfill in both parent and child pages.

Quick Start

Parent page — import to auto-register the element:

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

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

<script type="module">
  document.querySelector('mcp-iframe')
    .addEventListener('mcp-iframe-ready', (e) => {
      console.log('Tools:', e.detail.tools);
    });
</script>

Child page — register tools via @mcp-b/global:

import '@mcp-b/global';

navigator.modelContext.registerTool({
  name: 'calculate',
  description: 'Perform a calculation',
  inputSchema: { /* ... */ },
  execute: async (args) => ({ content: [{ type: 'text', text: 'Result' }] })
});

Item Prefixing

Items are exposed with the element’s id as prefix to prevent naming conflicts:

Child registers	Parent sees
`calculate`	`my-app:calculate`
`config://settings`	`my-app:config://settings`

Attributes

Standard iframe attributes (src, width, height, sandbox, etc.) are mirrored to the internal iframe.

MCP-Specific Attributes

Attribute	Default	Description
`target-origin`	Auto-detected	Origin for postMessage security
`channel`	`'mcp-iframe'`	Channel identifier
`call-timeout`	`30000`	Tool call timeout (ms)
`prefix-separator`	`':'`	Separator between prefix and name

Events

Event	Detail	Description
`mcp-iframe-ready`	`{ tools, resources, prompts }`	Connection established
`mcp-iframe-error`	`{ error }`	Connection failed
`mcp-iframe-tools-changed`	`{ tools, resources, prompts }`	Items refreshed

mcpIframe.addEventListener('mcp-iframe-ready', (e) => {
  console.log('Tools:', e.detail.tools);       // ['my-app:calculate', ...]
  console.log('Resources:', e.detail.resources);
  console.log('Prompts:', e.detail.prompts);
});

Properties & Methods

Property	Type	Description
`ready`	`boolean`	Connection status
`iframe`	`HTMLIFrameElement`	The wrapped iframe
`exposedTools`	`string[]`	Prefixed tool names
`exposedResources`	`string[]`	Prefixed resource URIs
`exposedPrompts`	`string[]`	Prefixed prompt names
`itemPrefix`	`string`	Current prefix (e.g., `my-app:`)

Method	Description
`refresh()`	Re-fetch items from iframe

Multiple Iframes

Each iframe uses its id as prefix:

<mcp-iframe src="./calc.html" id="calc"></mcp-iframe>
<mcp-iframe src="./todos.html" id="todos"></mcp-iframe>

Exposes: calc:add, calc:multiply, todos:create, todos:list, etc.

Cross-Origin

For cross-origin iframes, set target-origin explicitly:

<mcp-iframe
  src="https://other-domain.com/app.html"
  id="external"
  target-origin="https://other-domain.com"
></mcp-iframe>

The child must configure IframeChildTransport with allowed origins. See Security Guide for details.

Custom Registration

import { registerMCPIframeElement } from '@mcp-b/mcp-iframe';
registerMCPIframeElement('custom-mcp-frame');

Transports

Underlying IframeParentTransport

@mcp-b/global

Model Context API polyfill

Security

Origin validation

MCP UI Apps

Building embeddable apps

​Installation

​Quick Start

​Item Prefixing

​Attributes

​MCP-Specific Attributes

​Events

​Properties & Methods

​Multiple Iframes

​Cross-Origin

​Custom Registration

​Related