Skip to content
MSW Agent Tools

Installation

There are two tools to install depending on your use case:

ToolInstallBest for
msw-clinpm install -g msw-cliAny agent, script, or terminal workflow
msw-mcpMCP config (see below)AI assistants in Cursor, Claude Code, VS Code

Both tools require the browser client wired up in your frontend app.

1. Install the CLI or MCP server

Terminal window
npm install -g msw-cli

Verify the installation:

Terminal window
msw-cli --version

2. Set up the browser client

Your web app needs msw, @msw-mcp/client, a generated service worker, and a small mocks/ bridge so the CLI or MCP server can push handlers over WebSocket. Prefer an AI-assisted flow first — a coding agent runs msw-cli setup or /msw-setup and applies the printed steps (packages, msw init, files, env, entry wiring). Use manual setup when you want to do every step yourself.

Section titled “Recommended: scaffolding”

Pick the path that matches how you work:

Coding assistant + msw-cli setup

msw-cli setup only prints setup instructions to the terminal (a scaffold guide for your stack). It does not install packages, write files, or edit your app by itself. If you run it alone, you mostly get a checklist — you still need to follow it (or use manual setup below).

What to do instead: in your frontend project, ask your AI (Cursor Agent, Claude Code, etc.) to:

  1. Run msw-cli setup from the project root (with msw-cli installed globally). Optional hints: msw-cli setup --framework vite or msw-cli setup --help for flags.

    Terminal window
    msw-cli setup

  2. Treat the command output as the source of truth and continue the conversation so the assistant implements each step: add msw / @msw-mcp/client, run npx msw init …, create mocks/, set env files, and wire your entry point — matching what the printed guide says for your framework.

If your assistant cannot run shell commands, run msw-cli setup yourself and paste the full output into chat, then ask the assistant to perform the setup based on that output.

No msw-cli open session is required for setup (that command is only for live handler control after the app is wired up).

AI assistant — /msw-setup (MCP)

If msw-mcp is already configured in your MCP client, open a chat in that project and run:

/msw-setup

The assistant scaffolds the same pieces end to end (install, msw init, mocks/, .env.local, entry wiring). See the /msw-setup Prompt page for behavior and optional arguments.

Manual setup — expand for install commands and mocks/ walkthrough

Use this when you want full control or are migrating an existing MSW layout.

In your frontend project, install MSW and the published browser bridge @msw-mcp/client (the msw-mcp npm package is only the MCP server you run with npx msw-mcp, not the browser library):

Terminal window
npm install -D msw@^2.11.0 @msw-mcp/client

Initialize the MSW service worker (adjust public/ if your bundler uses another static dir):

Terminal window
npx msw init public/ --save

Then create the following files in a mocks/ directory at your project root.

  1. mocks/handlers.js — your base API handlers:

    import { http, HttpResponse } from 'msw';
    

    export const handlers = [
      // Add your static handlers here
    ];

  2. mocks/browser.js — the MSW worker setup:

    import { setupWorker } from 'msw/browser';
    import * as msw from 'msw';
    import { handlers } from './handlers';
    

    // Required: expose MSW utilities for the bridge
    if (typeof window !== 'undefined') {
      window.msw = msw;
    }
    

    export const worker = setupWorker(...handlers);

  3. mocks/index.js — initialization with the WebSocket bridge:

    import { initMocking } from '@msw-mcp/client';
    import { worker } from './browser';
    

    export async function enableMocking() {
      if (process.env.NODE_ENV !== 'development') return;
    

      const isMSWEnabled =
        process.env.ENABLE_MSW_MOCK === '1' ||
        process.env.ENABLE_MSW_MOCK === 'true';
    

      if (!isMSWEnabled) return;
    

      const isWSEnabled =
        process.env.ENABLE_MSW_WS_MOCK === '1' ||
        process.env.ENABLE_MSW_WS_MOCK === 'true';
    

      return initMocking({
        worker,
        wsEnabled: isWSEnabled,
        wsBridgeOptions: {
          url: process.env.MCP_SERVER_URL || 'ws://localhost:6789',
        },
        workerOptions: { onUnhandledRequest: 'bypass' },
      });
    }

  4. Import in your app entry point:

    import { enableMocking } from '../mocks';
    

    async function startApp() {
      await enableMocking();
      // ... rest of your app init
    }
    

    startApp();

  5. Create .env.local:

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

  6. Add to .gitignore (optional — for local-only custom handlers):

    mocks/custom-handlers/
    !mocks/custom-handlers/index.example.js

Next steps

Section titled “Next steps”