Skip to content
MSW Agent Tools

Configuration

Server flags

Section titled “Server flags”

| Flag | Default | Description | |------|---------|-------------| | --mock-ws-port <port> | 6789 | WebSocket server port | | --single-client | off | Only send messages to the most recently connected tab | | --persist-handlers | on | Persist all handlers to browser localStorage | | --no-persist-handlers | — | Disable handler persistence | | --persist-handlers=<N> | — | Persist only the N most recent handlers (FIFO) |

Usage examples

Section titled “Usage examples”
{
  "mcpServers": {
    "msw-mcp": {
      "command": "npx",
      "args": [
        "msw-mcp@latest",
        "--mock-ws-port=6789"
      ]
    }
  }
}

--mock-ws-port

Section titled “--mock-ws-port”

Sets the WebSocket port the browser bridge connects to. Must match MCP_SERVER_URL in your app’s .env.local.

Terminal window
# Server
npx msw-mcp@latest --mock-ws-port=3001


# App .env.local
MCP_SERVER_URL=ws://localhost:3001

--single-client

Section titled “--single-client”

By default, msw-mcp broadcasts to all connected browser tabs. Enable --single-client to send updates only to the most recently connected tab.

--persist-handlers

Section titled “--persist-handlers”

Handler persistence is enabled by default. Dynamically added handlers are saved to the browser’s localStorage under the key msw_dynamic_handlers and automatically restored on page refresh.

Terminal window
# Disable persistence
npx msw-mcp@latest --no-persist-handlers


# Persist only the 10 most recent handlers (FIFO)
npx msw-mcp@latest --persist-handlers=10

To manually clear persisted handlers in the browser console:

window.__mswBridge.clearPersistedHandlers();

Browser client options

Section titled “Browser client options”
interface EnableMockingOptions {
  worker: ServiceWorkerRegistration; // MSW worker instance (required)
  wsEnabled?: boolean;               // Enable WebSocket bridge (default: true)
  wsBridgeOptions?: {
    url?: string;                    // WebSocket URL (default: ws://localhost:6789)
    reconnectInterval?: number;      // Reconnect delay in ms (default: 5000)
    maxReconnectAttempts?: number;   // Max reconnect attempts (default: 10)
    enabled?: boolean;               // Toggle bridge on/off
  };
  workerOptions?: {
    onUnhandledRequest?: 'warn' | 'error' | 'bypass';
    quiet?: boolean;
    serviceWorker?: { url: string };
  };
}

Environment variables

Section titled “Environment variables”

| Variable | Default | Description | |----------|---------|-------------| | ENABLE_MSW_MOCK | — | Set to true or 1 to enable MSW | | ENABLE_MSW_WS_MOCK | — | Set to true or 1 to enable the WebSocket bridge | | MCP_SERVER_URL | ws://localhost:6789 | WebSocket server URL |

Create .env.local in your frontend project:

Terminal window
ENABLE_MSW_MOCK=true
ENABLE_MSW_WS_MOCK=true
MCP_SERVER_URL=ws://localhost:6789

Debugging the browser bridge

Section titled “Debugging the browser bridge”
// Check bridge state
window.__mswBridge


// Current WebSocket connection
window.__mswBridge.ws


// Currently active handlers
window.__mswBridge.activeHandlers


// Clear persisted handlers
window.__mswBridge.clearPersistedHandlers()