SEP: postMessage Transport

Preamble

Title: postMessage Transport
Author: Josh Mandel (@jmandel)
Status: Proposal
Type: Standards Track
Created: 2025-07-19
Full Spec Proposal: Draft
Reference Implementation: Demo | Source

Abstract

This SEP proposes a postMessage transport for the Model Context Protocol (MCP) that enables secure communication between clients and servers running in different browser contexts (iframes or popup windows). The transport leverages the browser's window.postMessage API to provide zero-installation MCP connections with support for a two-phase connection model: a one-time setup phase for configuration and authentication, and a transport phase for ongoing MCP communication. This approach enables new use cases including direct access to browser-sandboxed APIs, edge computing for privacy-sensitive applications, and rich user interfaces for MCP tools.

Motivation

Current MCP transports require either local installation or remote server processing, creating fundamental barriers to adoption and new capabilities:

Installation Barriers: STDIO servers require software installation, creating security risks from running untrusted code with system access and limiting reach to users who are willing to ignore these risks or have the technical expertise to mitigate them.

Privacy Trade-offs: Streamable HTTP servers require all relevant data to be present on or copied to a remove machine, which is undesirable in privacy-sensitive contexts.

Limited UX: MCP interactions are confined to text-based exchanges, preventing rich interactive experiences and progressive enhancement of client interfaces through embedded server UX.

Design Principles

This transport enables four transformative capabilities:

Zero Installation: Servers distributed as URLs eliminate installation friction and security risks, enabling instant access to MCP capabilities in browser-sandboxed environments.

Privacy-First Processing: Browser-local execution ensures sensitive data can stay on the user's device, enabling new classes of privacy-preserving AI tools.

Progressive UX Enhancement: Servers can embed rich interactive interfaces directly in client applications, transforming MCP from text-based to visually enhanced experiences.

Edge Computing: Computation occurs in the user's browser context, reducing latency and server costs while improving data locality.

Core Concepts

The postMessage transport is designed around two key sets of roles: the Window Hierarchy and the MCP Protocol Roles. Understanding their separation is crucial.

Window Hierarchy Roles (Physical Layer)

This describes the browser window relationship, which is what the transport components are built on.

• Outer Frame: The main, controlling window. It embeds and manages the other window.
• Inner Frame: The subordinate, controlled window, typically an <iframe> or a popup.

MCP Protocol Roles (Logical Layer)

This describes the roles defined by the Model Context Protocol itself.

• MCP Client: The entity that initiates actions by calling tools.
• MCP Server: The entity that provides tools and responds to tools/list.

Supported Architectures

By separating the window hierarchy from MCP roles, the transport supports two powerful patterns:

Standard Architecture (Client-in-Control)

• Outer Frame: MCP Client
• Inner Frame: MCP Server
• Use Case: A primary application (like a chat client) embeds and consumes tools from third-party services.

Inverted Architecture (Server-in-Control)

• Outer Frame: MCP Server
• Inner Frame: MCP Client
• Use Case: A primary application (like a user dashboard) provides contextual data as tools to an embedded, sandboxed AI copilot.

Protocol Overview

Two-Phase Connection Model

The transport uses distinct phases to handle server lifecycle:

1. Setup Phase (#setup hash): One-time server configuration and authentication
2. Transport Phase (no hash): Ongoing MCP communication with configured servers

Message Flow Diagram

sequenceDiagram
    participant OuterFrame
    participant SetupFrame as InnerFrame (Setup)
    participant TransportFrame as InnerFrame (Transport)

    Note over OuterFrame,SetupFrame: Setup Phase - Server Configuration
    OuterFrame->>OuterFrame: Start listening for messages
    OuterFrame->>SetupFrame: Create iframe, load server URL with #setup hash
    SetupFrame->>OuterFrame: SetupHandshake (targetOrigin: '*')
    OuterFrame->>SetupFrame: SetupHandshakeReply (sessionId, protocolVersion)
    Note over SetupFrame: Pin origin from event.origin<br/>Optional: Show setup UI
    SetupFrame->>OuterFrame: SetupComplete (displayName, transportVisibility)
    Note over OuterFrame: Persist server configuration<br/>Destroy setup iframe

    Note over OuterFrame,TransportFrame: Transport Phase - Active MCP Session (Later)
    OuterFrame->>OuterFrame: Start listening for messages
    OuterFrame->>TransportFrame: Create NEW iframe, load server URL (no hash)
    TransportFrame->>OuterFrame: TransportHandshake (targetOrigin: '*')
    OuterFrame->>TransportFrame: TransportHandshakeReply (same sessionId)
    Note over TransportFrame: Pin origin from event.origin
    TransportFrame->>OuterFrame: TransportAccepted

    Note over OuterFrame,TransportFrame: MCP Protocol Communication
    OuterFrame->>TransportFrame: MCPMessage (initialize)
    TransportFrame->>OuterFrame: MCPMessage (initialized)
    OuterFrame->>TransportFrame: MCPMessage (tools/list)
    TransportFrame->>OuterFrame: MCPMessage (tool definitions)
    OuterFrame->>TransportFrame: MCPMessage (tools/call)
    TransportFrame->>OuterFrame: MCPMessage (tool result)

Handshake Security

Origin Validation Protocol:

1. Inner Frame sends initial message with targetOrigin: '*' (doesn't know parent origin)
2. Outer Frame replies using Inner Frame's known origin
3. Inner Frame validates event.origin and pins it for all subsequent messages
4. All future communication uses pinned origins for security

Session Management:

• MCP Client generates unique sessionId for each server connection
• Server uses sessionId to scope persistent storage (API keys, preferences)
• Same sessionId used across setup and transport phases for data continuity

Permission Declaration System

Servers can declare browser permissions needed upfront:

requestedPermissions: [{
  name: "geolocation",
  phase: ["transport"],
  required: true,
  purpose: "To provide local weather forecasts and alerts"
}]

Benefits:

• Transparent Consent: Users see all permissions before embedding server
• Proactive Sandboxing: Clients configure iframe allow attributes automatically
• Security: Prevents hidden capability escalation during runtime

Version Negotiation

Setup handshake includes semantic version negotiation:

• Server declares supported version range (minProtocolVersion, maxProtocolVersion)
• Client selects highest compatible version within range
• Prevents compatibility issues between transport implementations

Transport Visibility Control

Servers specify their UI visibility needs during transport phase:

• hidden: Server runs invisibly (most common)
• optional: User can choose to show/hide server UI
• required: Server must remain visible (e.g., live visualizations)

Message Types

The protocol defines 8 message types with MCP_ prefix:

Setup Phase (3 messages):

• SetupHandshake → SetupHandshakeReply → SetupComplete

Transport Phase (5 messages):

• TransportHandshake → TransportHandshakeReply → TransportAccepted
• MCPMessage (bidirectional MCP protocol wrapper)
• SetupRequired (optional, triggers re-authentication)

Design Rationale

Key Design Decisions

This section explains the major design choices made in the postMessage transport and their rationale.

Two-Phase Protocol Design

Decision: Separate setup and transport phases with distinct handshake protocols.

Rationale:

• Invisible Server Configuration: Servers that run hidden during transport can still surface user-visible setup UI when first added, ensuring proper authentication and configuration even for background services
• Standard UX Pattern: Follows the familiar pattern where servers are configured once, then can be connected/disconnected repeatedly without reconfiguration - matching user expectations from other systems
• Persistent vs Ephemeral State: Setup handles persistent configuration (API keys, preferences) while transport handles ephemeral connection state, preventing configuration loss during reconnections
• Separation of Concerns: Configuration complexity is isolated from runtime performance, allowing transport phase to be lightweight and fast

Window Hierarchy vs MCP Role Separation

Decision: Distinguish "physical" browser window relationships from "logical" MCP client/server roles.

Rationale:

• Architectural Flexibility: Enables both standard (client-in-control) and inverted (server-in-control) patterns
• Composability: Applications can embed AI assistants or be embedded by them without protocol changes
• Clarity: Prevents confusion between browser containment and MCP responsibilities
• Innovation: Unlocks new patterns like dashboards providing contextual tools to embedded AI copilots

Origin-Based Security Model

Decision: Rely exclusively on browser's event.origin validation with explicit allowlists.

Rationale:

• Browser Native: Leverages the browser's tamper-proof origin enforcement
• No Custom Auth: Avoids complex authentication schemes that increase attack surface
• Simplified Implementation: Single validation point reduces security bugs
• Zero Trust: Every message is validated regardless of session state

Session ID Orchestration by Client

Decision: MCP Client generates and provides sessionId to MCP Server.

Rationale:

• Data Isolation: Servers can safely scope storage without collision risk
• Session Continuity: Clients can reuse sessions across page reloads
• Stateless Servers: Servers don't need to track active sessions globally
• Multi-Client Support: Same server can handle multiple client sessions independently

Permission Declaration System

Decision: Servers declare needed permissions upfront rather than requesting on-demand.

Rationale:

• Transparent Consent: Users see all permissions before embedding
• Sandbox Configuration: Clients can set restrictive iframe attributes proactively
• Security Principle: Explicit permission requests prevent hidden capability escalation
• User Control: Clients can reject servers with excessive permission requirements

Hash-Based Phase Detection

Decision: Use URL hash parameters (#setup vs no hash) to indicate protocol phase.

Rationale:

• Stateless Detection: Servers can determine phase without external state
• URL Simplicity: Same base URL serves both phases
• Browser Compatibility: Hash parameters work universally across browsers
• Developer Clarity: Visible indication of which phase is active

Alternative Approaches Considered

Single-Phase Protocol

Alternative: Combine setup and transport into single handshake.
Rejected Because: Would force all servers to show setup UI even when none needed, breaking "servers as URLs" goal.

Token-Based Authentication

Alternative: Use JWT or similar tokens for auth instead of origins.
Rejected Because: Increases complexity, requires key management, and adds attack vectors beyond browser's built-in security.

Server-Orchestrated Sessions

Alternative: Let servers generate their own session IDs.
Rejected Because: Creates collision risks, prevents client-controlled session continuity, and complicates multi-client scenarios.

Dynamic Permission Requests

Alternative: Allow runtime permission requests like mobile apps.
Rejected Because: Would surprise users with unexpected permission prompts and complicate client sandbox configuration.

Use Cases

Local File Access

Web-based servers can provide file access using the File System Access API:

• AI assistants work with local files without uploads
• Data never leaves the user's device
• Full read/write capabilities with user permission

Privacy-Preserving Edge Computing

Healthcare and financial applications process sensitive data locally:

• Patient records analyzed entirely in-browser
• Complex computations using WebAssembly
• No data transmission to external servers

Interactive Visualization Tools

Servers provide rich UI tools:

• Diagram editors (like mermaid.live)
• Data visualization dashboards
• Interactive form builders
• Real-time collaboration interfaces

Backwards Compatibility

As a new transport mechanism, the postMessage transport introduces no backwards compatibility issues. Existing MCP implementations using stdio or HTTP SSE transports continue to function unchanged. Clients and servers must explicitly opt into using the postMessage transport.

Reference Implementation

A complete reference implementation demonstrating all protocol features is available at https://github.com/jmandel/mcp-postmessage. A hosted demo of the implementation can be accessed at https://jmandel.github.io/mcp-postmessage.

Client Architecture

The demo client provides a full-featured MCP client interface that:

• Server Management: Add, configure, and connect to multiple PostMessage servers
• Setup Phase Handling: Manages both visible and hidden server setup workflows
• Tool Discovery: Automatically discovers and displays available MCP tools from connected servers
• Dynamic UI Generation: Creates forms for tool parameters based on MCP schema definitions
• Real-time Communication: Handles bidirectional MCP message exchange during active sessions

Example Servers

Transport Features by Example

The implementation includes four sample servers that demonstrate different protocol features:

Pi Calculator Server

• Demonstrates: No user-facing setup phase, optionally visible UI at runtime (hide/show buttons)
• Use Case: Mathematical computation with optional interactive visualization

JSON Analyzer Server

• Demonstrates: User-facing setup phase, hidden UI at runtime, partitioned storage by sessionId
• Use Case: Data processing and analysis with persistent configuration

Mermaid Editor Server

• Demonstrates: No user-facing setup phase, visible UI at runtime (always shown)
• Use Case: Interactive diagram editing requiring constant user visibility

Camera Tester Server

• Demonstrates: User-facing setup phase, optionally visible UI at runtime, partitioned storage by sessionId, dynamic permissions (camera access)
• Use Case: Privacy-preserving emotion analysis with on-demand camera access and AI integration

Each server demonstrates the complete protocol flow from setup through active MCP communication, providing practical patterns for implementers.

Security Implications

Validated Security Properties

1. Origin Isolation: Only explicitly allowed origins can establish connections
2. Message Integrity: PostMessage provides tamper-proof message delivery
3. Process Isolation: Browser contexts are isolated by default
4. No Ambient Authority: Each connection requires explicit handshake

Security Considerations

1. Iframe Sandboxing: Clients should apply appropriate sandbox attributes
2. Content Security Policy: Both parties should implement restrictive CSP
3. User Consent: Setup phase enables explicit permission flows
4. Data Validation: All message contents must be validated

Open Security Questions

The protocol addresses permission declaration and version negotiation. Additional areas for future consideration include standardized security profiles and cross-origin policy coordination.