This is a reference implementation for a proposed new transport for the Model Context Protocol (MCP) that enables zero-installation, browser-native MCP servers. The postMessage transport allows MCP servers to run directly in web browsers (iframes/popups) and communicate with clients using the browser's window.postMessage API, eliminating installation requirements while enabling rich interactive tools.

🌐 Try the Live Demo

📋 Read the Complete Protocol Specification for detailed technical documentation, message formats, and security requirements.

• Bun installed
• Modern web browser

1. Install dependencies:

   bun install

2. Start the demo:

   bun run dev

   This starts the demo server.

1. Build the complete demo application:

   bun run build

   This creates a dist/ folder with all assets bundled for deployment.

2. Preview the built application:

   bun run preview

3. Deploy to GitHub Pages: The repository includes GitHub Actions that automatically deploy to GitHub Pages on push to main branch.

4. Open your browser:

   • Client: http://localhost:3000
   • Pi Calculator: http://localhost:3001

1. Open the client at http://localhost:3000
2. Add the Pi Calculator server (should be pre-configured):
   • URL: http://localhost:3001#setup
3. Click "Setup" to configure the server
4. Click "Connect" to establish MCP connection
5. Try the interactive Pi calculation with Monte Carlo visualization

• Zero Installation: Servers run directly in browser
• Two-Phase Protocol: Setup → Transport phases
• Security: Origin validation and message routing
• Visibility Control: Optional/required/hidden server UI

• MCP Tool: calculate_pi method with configurable iterations
• Interactive UI: Real-time Monte Carlo visualization
• Progressive Calculation: Live progress updates
• Canvas Visualization: Points plotted inside/outside unit circle

├── src/
│   ├── client/           # Client transport implementation
│   ├── server/           # Server transport implementation
│   ├── types/            # TypeScript interfaces
│   └── utils/            # Helper functions
├── demo-client/          # React-based demo client
└── servers/
    └── pi-calculator/    # Monte Carlo Pi calculator server

• Bun installed
• Modern web browser

# Install dependencies
bun install

# Type checking
bun run type-check

# Build for production
bun run build

# Start individual components
bun run demo:client    # Client on port 3000
bun run demo:pi       # Pi Calculator on port 3001

# Start complete demo (client + Pi server)
bun run demo

The postMessage transport implements a two-phase connection model:

1. Setup Phase (#setup parameter):

   • Server announces readiness
   • Client performs handshake
   • User completes configuration
   • Server reports setup completion

2. Transport Phase (normal URL):

   • Server announces transport readiness
   • Client establishes MCP connection
   • Standard MCP protocol communication

• Origin Validation: All messages validated against allowed origins
• Message Routing: Proper postMessage target origin handling
• Iframe Sandboxing: Secure execution environment
• No Ambient Authority: Explicit connection handshakes required

MIT License - see LICENSE file for details.