WebMCP Documentation

Browser transport implementations for the Model Context Protocol. Each transport class implements the MCP Transport interface and handles JSON-RPC 2.0 message serialization, origin validation, and connection lifecycle.

Installation

pnpm add @mcp-b/transports

Peer dependency: @mcp-b/webmcp-ts-sdk (included transitively).

Minimal example

Which transport to use

Scenario	Server	Client
Same-page communication	`TabServerTransport`	`TabClientTransport`
Parent page to iframe	`IframeChildTransport` (in iframe)	`IframeParentTransport` (in parent)
Extension to webpage	`ExtensionServerTransport` (in background)	`ExtensionClientTransport` (in sidebar/popup)
Extension to extension	`ExtensionServerTransport` (in host extension)	`ExtensionExternalClientTransport` (in guest extension)
User script to extension	`UserScriptServerTransport` (in background)	`UserScriptClientTransport` (in user script)

Tab transports

In-page communication via window.postMessage. Both server and client run in the same browser tab.

TabServerTransport

Listens for MCP messages on the current window. Broadcasts a mcp-server-ready signal on start.

import { TabServerTransport } from '@mcp-b/transports';

const transport = new TabServerTransport({
  allowedOrigins: ['https://example.com'],
});
await server.connect(transport);

TabServerTransportOptions

Option	Type	Required	Default	Description
`allowedOrigins`	`string[]`	Yes	—	Origins permitted to send messages. Use `["*"]` to allow any origin.
`channelId`	`string`	No	`"mcp-default"`	Channel identifier for message routing. Multiple transports can coexist on the same page with different channel IDs.

Behavior

Validates event.origin against allowedOrigins for every incoming message.
Tracks pending requests and sends interrupted responses during beforeunload if the page navigates while a tool call is in progress.
Cleans up stale requests after 5 minutes.
Posts mcp-server-stopped on close.

TabClientTransport

Connects to a TabServerTransport in the same window. Waits for a server-ready handshake before sending messages.

import { TabClientTransport } from '@mcp-b/transports';

const transport = new TabClientTransport({
  targetOrigin: window.location.origin,
});
await client.connect(transport);

TabClientTransportOptions

Option	Type	Required	Default	Description
`targetOrigin`	`string`	No	`"*"`	Expected origin of the server window. Messages from other origins are ignored.
`channelId`	`string`	No	`"mcp-default"`	Channel identifier for message routing.
`requestTimeout`	`number`	No	`10000`	Timeout in milliseconds for requests. If the server does not respond in time, a JSON-RPC error with code `-32000` is synthesized.

Properties

Property	Type	Description
`serverReadyPromise`	`Promise<void>`	Resolves when the server signals readiness. `send()` awaits this automatically.

Server discovery

TabClientTransport does not have a standalone discover() method. The server-ready handshake (mcp-check-ready / mcp-server-ready) is handled internally during start().

Iframe transports

Cross-origin communication between a parent page and an iframe. Uses window.postMessage with retry-based ready handshakes to handle iframe loading timing.

IframeParentTransport

Client-side transport for the parent page. Sends messages into the iframe’s contentWindow.

import { IframeParentTransport } from '@mcp-b/transports';

const iframe = document.querySelector('iframe');
const transport = new IframeParentTransport({
  iframe,
  targetOrigin: 'https://iframe-app.com',
});
await client.connect(transport);

IframeParentTransportOptions

Option	Type	Required	Default	Description
`iframe`	`HTMLIFrameElement`	Yes	—	Reference to the iframe element.
`targetOrigin`	`string`	No	`"*"`	Expected origin of the iframe for `postMessage` security.
`channelId`	`string`	No	`"mcp-iframe"`	Channel identifier for message routing.
`checkReadyRetryMs`	`number`	No	`250`	Interval in milliseconds to retry the ready handshake if the iframe is not yet ready.

Properties

Property	Type	Description
`serverReadyPromise`	`Promise<void>`	Resolves when the iframe’s server signals readiness.

IframeChildTransport

Server-side transport for code running inside an iframe. Sends messages to window.parent.

import { IframeChildTransport } from '@mcp-b/transports';

const transport = new IframeChildTransport({
  allowedOrigins: ['https://parent-app.com'],
});
await server.connect(transport);

IframeChildTransportOptions

Option	Type	Required	Default	Description
`allowedOrigins`	`string[]`	Yes	—	Parent origins permitted to connect. Use `["*"]` to allow any origin.
`channelId`	`string`	No	`"mcp-iframe"`	Channel identifier for message routing.
`serverReadyRetryMs`	`number`	No	`250`	Interval in milliseconds to retry broadcasting the ready signal to the parent.

Extension transports

Communication between Chrome extension components using chrome.runtime.Port. Used for connecting content scripts, sidebars, and popups to the extension’s background service worker.

ExtensionServerTransport

Wraps a chrome.runtime.Port to handle a single client connection. Runs in the background service worker.

import { ExtensionServerTransport } from '@mcp-b/transports';

chrome.runtime.onConnect.addListener((port) => {
  if (port.name === 'mcp') {
    const transport = new ExtensionServerTransport(port);
    await server.connect(transport);
  }
});

Constructor

new ExtensionServerTransport(port: chrome.runtime.Port, options?: ExtensionServerTransportOptions)

ExtensionServerTransportOptions

Option	Type	Required	Default	Description
`keepAlive`	`boolean`	No	`true`	Send periodic keep-alive pings to prevent service worker shutdown.
`keepAliveInterval`	`number`	No	`1000`	Keep-alive interval in milliseconds.

Methods

Method	Returns	Description
`getConnectionInfo()`	`{ connectedAt, lastMessageAt, messageCount, uptime, isConnected }`	Connection statistics.

ExtensionClientTransport

Connects to the extension’s background service worker via chrome.runtime.connect. Supports automatic reconnection with exponential backoff.

import { ExtensionClientTransport } from '@mcp-b/transports';

const transport = new ExtensionClientTransport({
  portName: 'mcp',
});
await client.connect(transport);

ExtensionClientTransportOptions

Option	Type	Required	Default	Description
`extensionId`	`string`	No	—	Extension ID to connect to. Omit for same-extension connections. When provided, uses `chrome.runtime.connect(extensionId, ...)` for cross-extension communication.
`portName`	`string`	No	`"mcp"`	Port name for the connection.
`autoReconnect`	`boolean`	No	`true`	Reconnect automatically on disconnect.
`maxReconnectAttempts`	`number`	No	`10`	Maximum reconnection attempts before giving up.
`reconnectDelay`	`number`	No	`1000`	Initial reconnection delay in milliseconds.
`maxReconnectDelay`	`number`	No	`30000`	Maximum reconnection delay in milliseconds.
`reconnectBackoffMultiplier`	`number`	No	`1.5`	Multiplier applied to the delay after each failed attempt.

User script transports

Communication between Chrome MV3 user scripts and the extension’s background service worker. Connections arrive via chrome.runtime.onUserScriptConnect on the extension side.

UserScriptServerTransport

Identical in API to ExtensionServerTransport. Wraps a chrome.runtime.Port received from a user script connection.

import { UserScriptServerTransport } from '@mcp-b/transports';

chrome.runtime.onUserScriptConnect.addListener((port) => {
  const transport = new UserScriptServerTransport(port);
  await server.connect(transport);
});

UserScriptServerTransportOptions

Option	Type	Required	Default	Description
`keepAlive`	`boolean`	No	`true`	Send periodic keep-alive pings.
`keepAliveInterval`	`number`	No	`1000`	Keep-alive interval in milliseconds.

UserScriptClientTransport

Identical in API to ExtensionClientTransport. Connects from a user script context to the extension background.

UserScriptClientTransportOptions

Option	Type	Required	Default	Description
`extensionId`	`string`	No	—	Extension ID to connect to.
`portName`	`string`	No	`"mcp"`	Port name for the connection.
`autoReconnect`	`boolean`	No	`true`	Reconnect automatically on disconnect.
`maxReconnectAttempts`	`number`	No	`10`	Maximum reconnection attempts.
`reconnectDelay`	`number`	No	`1000`	Initial reconnection delay in milliseconds.
`maxReconnectDelay`	`number`	No	`30000`	Maximum reconnection delay in milliseconds.
`reconnectBackoffMultiplier`	`number`	No	`1.5`	Backoff multiplier per failed attempt.

Security

All transports enforce origin or connection validation:

Transport type	Security mechanism
Tab	`allowedOrigins` on server, `targetOrigin` on client. Messages from non-matching origins are silently dropped.
Iframe	Same as tab transports. Cross-origin `postMessage` with origin checks on both sides.
Extension	Chrome’s port-based messaging API. Only code within the extension (or extensions listed in `externally_connectable`) can connect.
Extension External	Requires `externally_connectable` in `manifest.json`. Server should validate `port.sender.id` before accepting connections.
User Script	Chrome’s `onUserScriptConnect` API. Only registered user scripts can initiate connections.

Setting allowedOrigins to ["*"] or targetOrigin to "*" disables origin validation. Use specific origins in production.

Common transport interface

Every transport class implements the MCP Transport interface:

Member	Type	Description
`start()`	`Promise<void>`	Begin listening for messages.
`send(message)`	`Promise<void>`	Send a JSON-RPC 2.0 message.
`close()`	`Promise<void>`	Stop listening and clean up resources.
`onmessage`	`(message: JSONRPCMessage) => void`	Callback for incoming messages.
`onerror`	`(error: Error) => void`	Callback for errors.
`onclose`	`() => void`	Callback when the transport closes.

Transports and bridges for the conceptual architecture behind transport design
Bridge tools across iframes for a step-by-step iframe bridging guide
Connect desktop agents with local relay for stdio-to-browser bridging
@mcp-b/mcp-iframe for the high-level <mcp-iframe> custom element that wraps iframe transports

Packages

WebMCP standard

Core runtime

React

Tooling

@mcp-b/transports

Installation

Minimal example

Which transport to use

Tab transports

TabServerTransport

TabServerTransportOptions

Behavior

TabClientTransport

TabClientTransportOptions

Properties

Server discovery

Iframe transports

IframeParentTransport

IframeParentTransportOptions

Properties

IframeChildTransport

IframeChildTransportOptions

Extension transports

ExtensionServerTransport

Constructor

ExtensionServerTransportOptions

Methods

ExtensionClientTransport

ExtensionClientTransportOptions

User script transports

UserScriptServerTransport

UserScriptServerTransportOptions

UserScriptClientTransport

UserScriptClientTransportOptions

Security

Common transport interface

​Installation

​Minimal example

​Which transport to use

​Tab transports

​TabServerTransport

​TabServerTransportOptions

​Behavior

​TabClientTransport

​TabClientTransportOptions

​Properties

​Server discovery

​Iframe transports

​IframeParentTransport

​IframeParentTransportOptions

​Properties

​IframeChildTransport

​IframeChildTransportOptions

​Extension transports

​ExtensionServerTransport

​Constructor

​ExtensionServerTransportOptions

​Methods

​ExtensionClientTransport

​ExtensionClientTransportOptions

​User script transports

​UserScriptServerTransport

​UserScriptServerTransportOptions

​UserScriptClientTransport

​UserScriptClientTransportOptions

​Security

​Common transport interface

​Related

Installation

Minimal example

Which transport to use

Tab transports

TabServerTransport

TabServerTransportOptions

Behavior

TabClientTransport

TabClientTransportOptions

Properties

Server discovery

Iframe transports

IframeParentTransport

IframeParentTransportOptions

Properties

IframeChildTransport

IframeChildTransportOptions

Extension transports

ExtensionServerTransport

Constructor

ExtensionServerTransportOptions

Methods

ExtensionClientTransport

ExtensionClientTransportOptions

User script transports

UserScriptServerTransport

UserScriptServerTransportOptions

UserScriptClientTransport

UserScriptClientTransportOptions

Security

Common transport interface

Related