Prerequisites
- @modelcontextprotocol/sdk - Official MCP SDK
- Modern browser with ES2020+ support
- TypeScript 5.0+ (recommended for type safety)
- Chrome Extension Manifest V3 (for extension transports)
- Understanding of async/await and Promises
Installation
Transport Types
Tab Transports (In-Page Communication)
UseTabServerTransport and TabClientTransport when your MCP server and client are running in the same browser tab. The transport uses window.postMessage for secure communication with origin validation.
Iframe Transports (Parent-Child Communication)
UseIframeParentTransport and IframeChildTransport for cross-origin communication between a parent page and an iframe. These transports are specifically designed for iframe scenarios and support cross-origin messaging.
Extension Transports (Cross-Context Communication)
UseExtensionClientTransport and ExtensionServerTransport for communication between browser extension components (sidebar, popup, background) and web pages with MCP servers.
Tab Transport Examples
Server Setup (Web Page)
Create an MCP server in your web page and expose it viaTabServerTransport:
Client Setup (Same Page)
Connect to the server from within the same page or from an extension content script:Iframe Transport Examples
Server Setup (Inside Iframe)
Create an MCP server inside an iframe that can be accessed by the parent page:Client Setup (Parent Page)
Connect from the parent page to the iframe’s MCP server:Extension Transport Examples
Background Script Setup
The extension background script acts as a hub, aggregating tools from multiple tabs:Content Script Bridge
Content scripts act as a bridge between the page’s MCP server and the extension:Extension UI Client
Connect from the extension’s sidebar or popup to use tools from all connected pages:Configuration Options
ExtensionServerTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
port | chrome.runtime.Port | Yes | Chrome runtime port object |
keepAlive | boolean | No | Enable keep-alive ping/pong (default: false) |
keepAliveInterval | number | No | Keep-alive interval in ms (default: 30000) |
ExtensionClientTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
portName | string | No | Port name for connection (default: ‘mcp’) |
autoReconnect | boolean | No | Auto-reconnect on disconnect (default: false) |
extensionId | string | No | Target extension ID (for cross-extension) |
TabServerTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
allowedOrigins | string[] | Yes | Array of allowed origins or ['*'] for all |
TabClientTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
targetOrigin | string | Yes | Origin of the target window |
IframeParentTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
iframe | HTMLIFrameElement | Yes | Reference to the iframe element |
targetOrigin | string | Yes | Expected origin of the iframe (for security) |
channelId | string | No | Channel identifier (default: ‘mcp-iframe’) |
checkReadyRetryMs | number | No | Retry interval for ready handshake in ms (default: 250) |
IframeChildTransport Options
| Option | Type | Required | Description |
|---|---|---|---|
allowedOrigins | string[] | Yes | Whitelist of parent origins allowed to connect |
channelId | string | No | Channel identifier (default: ‘mcp-iframe’) |
serverReadyRetryMs | number | No | Retry interval for broadcasting ready signal in ms (default: 250) |
Key Features
- Automatic Server Discovery: Tab clients can discover available servers
- Cross-Origin Support: Configure CORS for tab and iframe transports
- Parent-Child Communication: Iframe transports enable secure cross-origin iframe communication
- Ready Handshake Protocol: Iframe transports handle iframe loading timing issues automatically
- Cross-Extension Communication: Extensions can expose APIs to other extensions
- Tool Namespacing: Extension hub prefixes tools to avoid conflicts
- Connection Management: Automatic cleanup when tabs close
- Keep-Alive Support: Maintain persistent connections
- Type Safety: Full TypeScript support with proper typing
Security Considerations
- Tab transports respect origin restrictions
- Iframe transports validate origins on both parent and child sides
- Always specify explicit
targetOrigin(never use'*'in production) - Configure
allowedOriginsto whitelist only trusted parent domains - Use
postMessageAPI for secure cross-origin communication
- Always specify explicit
- Extension transports use Chrome’s secure message passing
- External extension transports require
externally_connectablemanifest configuration - Server extensions should validate incoming connections from other extensions
- Configure
allowedOriginsappropriately for your use case - Tools execute in their original context (web page, iframe, or extension)
Related Documentation
@mcp-b/global
Web Model Context API polyfill
@mcp-b/react-webmcp
React hooks for MCP
@mcp-b/extension-tools
Chrome Extension API wrappers
Core Concepts
Transport architecture diagrams
- Advanced Patterns - Extension and multi-tab scenarios
- Security Guide - Origin validation and transport security
- Troubleshooting - Common transport issues
External Resources
- @modelcontextprotocol/sdk - Official MCP SDK
- MCP Protocol Specification - Protocol details
- Chrome Extension Development - Extension APIs
- GitHub Repository - Source code
