DebugAIdocs

Windsurf

Give Windsurf's agent the DebugAI tools with one command, alongside or instead of the editor extension.

Windsurf's agent gets the three DebugAI tools: lookup_error, debug_error and report_outcome. You need Node.js 18.14.1 or later. node -v prints your version.

Windsurf can also run the DebugAI extension from Open VSX, for the editor commands and fixes you apply as a diff. That is a separate install, covered in Cursor, Windsurf, VSCodium. This page is the MCP server for Windsurf's agent.

Run setup

npx -y @debugai/mcp setup

It signs you in through your browser with a short code (free account, 10 debugs a day, no card). Then it adds DebugAI to every MCP client it finds on this machine, Windsurf included, and finishes by running doctor to check the result.

To change Windsurf's config and nothing else:

npx -y @debugai/mcp login
npx -y @debugai/mcp install --client=windsurf

Add --dry-run to the install line to print the change without writing anything.

Refresh Windsurf's MCP list

Open Windsurf, go to Settings, then MCP, and press refresh.

Check it works

Run npx -y @debugai/mcp doctor. Under MCP clients you want this line:

✓ Windsurf — debugai configured

Then hand Windsurf's agent an error and ask for the lookup by name:

Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name')

lookup_error makes no model call and does not count against your daily limit, so this check is free.

You'll know it worked when

The agent calls lookup_error and gets back a line like Not seen before in this project (shop). Call debug_error with the full error for an analysis. The name in brackets is your project's folder.

Make the agent reach for it

When Windsurf connects, the server tells the agent what the tools are for. A rule in whatever rules file your agent reads makes the habit dependable:

When a command fails, call the debugai lookup_error tool first: it is
instant and free. If it has no confirmed fix, call debug_error before
attempting your own, and pass the command that reproduces the failure
as reproCommand. After applying a fix, call report_outcome so the
project's error memory stays accurate.

The config it writes

setup adds one entry to mcpServers in ~/.codeium/windsurf/mcp_config.json. On Windows, ~ is your user folder, C:\Users\<you>.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp@latest"]
    }
  }
}
  • Your key is never written into this file. It lives in ~/.debugai/config.json with 0600 permissions, and every MCP client on the machine reads it from there.
  • Before changing the file, install saves a copy beside it, named mcp_config.json.debugai-backup-<timestamp>. Every other setting in the file is kept.
  • If the file has comments, the rewrite drops them, and install warns you when it does. The backup keeps them.
  • npx -y @debugai/mcp uninstall takes the entry out of every client config again.

Next

Cursor

Give Cursor's agent the DebugAI tools with one command, alongside or instead of the editor extension.

Claude Desktop

Add the DebugAI tools to the Claude Desktop app with one command, then tell it which project you mean.

On this page

1Run setup2Refresh Windsurf's MCP list3Check it worksMake the agent reach for itThe config it writesNext