Documentation · MCP · Windsurf

Debug browser bugs in Windsurf — from real evidence

Windsurf's Cascade agent reads MCP servers from a global config file. One small file, and Cascade can read every TraceBug export on your machine. Everything runs locally: the server is stdio-only, opens zero network connections, and reads report files from your disk. See the unedited transcript of Claude going from crash to root cause in five tool calls.

  1. 1

    Create the config file

    Add the tracebug entry to ~/.codeium/windsurf/mcp_config.json (create the file if it doesn't exist). You can also reach this file from Windsurf: Settings → Cascade → MCP → Configure.

    ~/.codeium/windsurf/mcp_config.json
    {
  "mcpServers": {
    "tracebug": {
      "command": "npx",
      "args": ["-y", "tracebug", "mcp"]
    }
  }
}
  2. 2

    Refresh the servers

    In the Cascade panel, open the MCP toolbar and hit Refresh (or restart Windsurf). tracebug should appear in the server list with its six tools.

  3. 3

    Capture a bug and ask

    Export a bug with the TraceBug extension, then tell Cascade: "List my bug reports and investigate the newest one." The server auto-discovers exports in Downloads and Desktop; add "--dir", "./bug-reports" to the args array to pin a project folder.

Verify it worked

The Cascade MCP list shows tracebug as running. Ask Cascade "what MCP tools do you have?" and look for list_bug_reports.

Troubleshooting

Server never appears after refresh
Validate the JSON (a trailing comma is the usual culprit) and make sure npx (Node 18+) is on your PATH, then restart Windsurf.
Tools error on first call
Windsurf may require you to approve the server's tools once — check the Cascade panel for a pending approval.
list_bug_reports returns nothing
Capture and Export .html first, or point --dir at the folder holding your exports.
No bug handy? Make one.
The live sandbox has intentional bugs — capture one, export it, and hand it to Windsurf.
Open the sandbox

Full MCP reference — all six tools, the report format, and the FAQ — lives at /docs/mcp. Other tools: Claude Code · Cursor.