Browser context transport

[AdirD]

Browser-based MCP Transport Implementation

Added a browser-based MCP transport implementation to enable client-server communication entirely within the browser environment.

#219

Motivation and Context

• There's increasing demand for applications that can run entirely in the browser
• Current transport implementations (stdio, SSE) require separate processes or HTTP endpoints, which isn't suitable for browser based applications, like browser extensions, static web apps, or embedded components.
• The new BrowserContextTransport allows for MCP servers to run directly in the browser alongside clients, enabling new application architectures.

How Has This Been Tested?

• Tested in browser environment with basic client-server communication
• Tested with Web Workers scenario for isolated server execution
• Tested with iframes for cross-domain scenarios

Breaking Changes

None. This is a new addition that doesn't affect existing functionality.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The implementation uses the browser's MessageChannel API to create paired channels for bidirectional communication between MCP client and MCP server.

Resources

• 📚 MessageChannel API Documentation

Quick Start Examples

Creating a Transport Pair

Most basic use case - both ends in same context:

// Import the necessary components
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { BrowserContextTransport } from '@modelcontextprotocol/sdk/browser-context-transport.js';

async function setupMcpInBrowser() {
  // Create a connected pair of transports
  const [clientTransport, serverTransport] = BrowserContextTransport.createChannelPair();
  
  // Create and set up the client
  const client = new Client(
    { name: "browser-client", version: "1.0.0" },
    { capabilities: { tools: {}, resources: {}, prompts: {} } }
  );
  
  // Create and set up the server
  const server = new Server(
    { name: "browser-server", version: "1.0.0" },
    { capabilities: { tools: {}, resources: {}, prompts: {} } }
  );
  
  // Connect the transports to their respective endpoints
  await server.connect(serverTransport);
  await client.connect(clientTransport);
  
  // Initialize the client
  await client.initialize();
  
  return { client, server };
}

With Web Workers

For cases where you want to run the server in a Web Worker:

// In your main application
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { BrowserContextTransport } from '@modelcontextprotocol/sdk/browser-context-transport.js';

async function createWorkerServerClient() {
  // Create a worker
  const worker = new Worker('server-worker.js');
  
  // Create a MessageChannel to communicate with the worker
  const channel = new MessageChannel();
  
  // Pass port2 to the worker
  worker.postMessage({ type: 'INIT_PORT' }, [channel.port2]);
  
  // Create a client with port1
  const client = new Client(
    { name: "browser-client", version: "1.0.0" },
    { capabilities: { tools: {}, resources: {}, prompts: {} } }
  );
  
  const transport = new BrowserContextTransport(channel.port1);
  await client.connect(transport);
  await client.initialize();
  
  return client;
}

// In server-worker.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { BrowserContextTransport } from '@modelcontextprotocol/sdk/browser-context-transport.js';

let serverTransport;
let server;

// Listen for the port to be transferred
self.onmessage = async (event) => {
  if (event.data && event.data.type === 'INIT_PORT') {
    const port = event.ports[0];
    
    // Create server
    server = new Server(
      { name: "worker-server", version: "1.0.0" },
      { capabilities: { tools: {}, resources: {}, prompts: {} } }
    );
    
    // Create transport with the received port
    serverTransport = new BrowserContextTransport(port);
    
    // Connect the server
    await server.connect(serverTransport);
    
    // Remove this general message handler since we'll now use the transport
    self.onmessage = null;
  }
};

With Iframes

For cross-domain scenarios, you might want to use iframes:

// In the parent window
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { BrowserContextTransport } from '@modelcontextprotocol/sdk/browser-context-transport.js';

async function createIframeServerClient() {
  // Create an iframe
  const iframe = document.createElement('iframe');
  iframe.src = 'https://example.com/server-frame.html';
  document.body.appendChild(iframe);
  
  // Create a MessageChannel
  const channel = new MessageChannel();
  
  // Wait for iframe to load
  await new Promise(resolve => {
    iframe.onload = resolve;
  });
  
  // Transfer port2 to the iframe
  iframe.contentWindow.postMessage({ type: 'INIT_PORT' }, '*', [channel.port2]);
  
  // Create a client with port1
  const client = new Client(
    { name: "browser-client", version: "1.0.0" },
    { capabilities: { tools: {}, resources: {}, prompts: {} } }
  );
  
  const transport = new BrowserContextTransport(channel.port1);
  await client.connect(transport);
  await client.initialize();
  
  return client;
}

// In the iframe (server-frame.html)
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { BrowserContextTransport } from '@modelcontextprotocol/sdk/browser-context-transport.js';

window.addEventListener('message', async (event) => {
  if (event.data && event.data.type === 'INIT_PORT') {
    const port = event.ports[0];
    
    // Create server
    const server = new Server(
      { name: "iframe-server", version: "1.0.0" },
      { capabilities: { tools: {}, resources: {}, prompts: {} } }
    );
    
    // Create transport with the received port
    const serverTransport = new BrowserContextTransport(port);
    
    // Connect the server
    await server.connect(serverTransport);
  }
}, { once: true });

[the-vampiire]

in the sse transport the crypto UUID is used. there is a browser compatible implementation that can be used

[AdirD]

You're right, updated

[Alpsli]

It's not released yet now. How can I experience this feature?

[jspahrsummers]

I appreciate the work that's gone into this implementation, and have done similar things in my own projects, but I don't think we should include this in the SDK. The SDK should remain focused only on the things that are part of the standard MCP spec.

Perhaps it'd be useful to maintain this as its own, separate npm package?