Skip to content
MSW Agent Tools

msw-mcp Overview

msw-mcp is a Model Context Protocol server that gives AI assistants — in Cursor, Claude Code, VS Code, Windsurf, and other MCP clients — the ability to add, update, remove, and inspect MSW request handlers in a live browser tab.

It shares the same WebSocket daemon as msw-cli, powered by @msw-mcp/core.

Architecture

Section titled “Architecture”
┌─────────────────┐  MCP (stdio)  ┌──────────────────────┐  WebSocket  ┌──────────────────┐
│                 │──────────────►│                      │────────────►│                  │
│  AI assistant   │               │  msw-mcp server      │             │  Browser + MSW   │
│  (Cursor, etc.) │               │  (port 6789)         │             │  service worker  │
│                 │◄──────────────│                      │◄────────────│                  │
└─────────────────┘               └──────────────────────┘             └──────────────────┘
  1. The AI assistant connects to msw-mcp over stdio using the MCP protocol.
  2. msw-mcp embeds an HTTP + WebSocket server from @msw-mcp/core.
  3. The browser app (with @msw-mcp/client) connects to the WebSocket.
  4. When the AI calls a tool (e.g., msw_add_handlers), the server forwards the handler code over WebSocket.
  5. MSW evaluates the handler code and the mock activates instantly.

What the AI can do

Section titled “What the AI can do”

Generate handlers from natural language

“Create a REST API for user management with CRUD operations” → AI writes and applies the handler code.

Update existing mocks

“Make the /users endpoint return a 500 error” → AI calls msw_update_handlers to replace the handler atomically.

Mock external APIs

“Mock the GitHub API to return fake repo data” → handlers for api.github.com endpoints are injected into the service worker.

Inspect state

msw_get_status returns whether the browser is connected, the worker status, and a summary of all active handlers.

Five MCP tools

Section titled “Five MCP tools”

| Tool | Purpose | |------|---------| | msw_add_handlers | Add handler code strings; optional once for one-time handlers | | msw_update_handlers | Replace handlers matching URL patterns (atomic) | | msw_remove_handlers | Remove handlers by URL patterns and optional HTTP methods | | msw_reset_handlers | Clear runtime handlers or set an explicit new list | | msw_get_status | Report browser connection and active handler list |

See MCP Tools for full parameter reference and examples.

Automated setup with /msw-setup

Section titled “Automated setup with /msw-setup”

The /msw-setup prompt automatically scaffolds the frontend integration:

/msw-setup

The AI will:

  • Detect your framework (React, Vue, Svelte, vanilla JS, …)
  • Install msw and msw-mcp dependencies
  • Create the complete mocks/ directory structure
  • Configure environment variables
  • Integrate with your app entry point
  • Migrate existing MSW setups if already present

See /msw-setup Prompt for details.

Supported MCP clients

Section titled “Supported MCP clients”

msw-mcp works with any MCP-compatible client that supports the stdio transport:

  • Cursor
  • Claude Code (claude mcp add)
  • VS Code (Copilot MCP)
  • Windsurf
  • Cline / Roo Cline
  • Gemini CLI
  • Any other client following the MCP spec

Next steps

Section titled “Next steps”