@debugai/mcp

@debugai/mcp

DebugAI as an MCP server. Your agent hands an error to debug_error and getsback the root cause plus up to 3 ranked fixes with code patches. Works inClaude Desktop, Claude Code, Cursor, Zed, Windsurf, and any other MCP client.

Until now this server only shipped inside theDebugAI VS Code extension.This package is the same server, standalone. No VS Code required.

Setup

1. Create a free account at debugai.io (10 debugs/day, no card).
2. Copy your API key (dbg_...) from debugai.io/dashboard.
3. Add the server to your MCP client (snippets below). Node 18+ required.

Set the key once for every client (optional)

Instead of repeating the key in each client's env block, write it to~/.debugai/config.json:

{ "api_key": "dbg_your_key_here" }

Every MCP client launching npx -y @debugai/mcp picks it up — you can thendrop the env block from the snippets below entirely. An explicitDEBUGAI_API_KEY env var still wins over the file.

Claude Code

claude mcp add debugai --env DEBUGAI_API_KEY=dbg_your_key_here -- npx -y @debugai/mcp

Claude Desktop

claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp"],
      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
    }
  }
}

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json per project):

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp"],
      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
    }
  }
}

Zed

settings.json:

{
  "context_servers": {
    "debugai": {
      "command": {
        "path": "npx",
        "args": ["-y", "@debugai/mcp"],
        "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp"],
      "env": { "DEBUGAI_API_KEY": "dbg_your_key_here" }
    }
  }
}

VS Code

You don't need this package. TheDebugAI extensionregisters the MCP server automatically (VS Code 1.101+) and adds one-clickfix apply, proactive scan, and codebase indexing on top.

The tools

debug_error

Give it an error, get an analysis.

Returns the root cause, up to 3 fixes ranked by confidence, the detectedframework, and whether the answer came from cache. Since 2.0 each fix alsocarries, where derivable: edits (exact old/new strings your agent's edittool can apply directly), unified_diff, and verify_with (a syntax-levelcheck command to run after applying). Read-only: it never touches yourfiles. Applying a fix is your agent's (and your) call.

Every fix is labeled with its verification state, and there are three ofthem, not two: verified (a mechanical check passed — currentlyparse/import classes), failed check (confidence capped hard), or notverified (the confidence number is the model's own estimate — nothingchecked it). We label the third case instead of hiding it.

report_outcome

Tell DebugAI whether an applied fix actually worked.

Confirmed rank-1 fixes are remembered per project (the next hit on the sameerror starts from the confirmed fix); failed-fix follow-ups are thefeedback that improves future answers. Agents are asked to call this onceper applied fix — same pipeline human feedback flows through in the VS Codeextension.

Example, in Claude Code:

Paste a traceback and ask "why is this failing?". Claude callsdebug_error and gets back something like:

Root cause: db.session is used after the request context closed.Fix 1 (94% confidence): move the query inside the request handler...

Environment variables

Limits and honesty

• Free tier: 10 debugs/day. Pro ($12/mo): 1,000/mo soft cap, never hard-blocked at it.
• When you hit the daily cap the tool says so and stops. It will not silently retry.
• Simple errors route to a fast model; ugly cross-file ones route to astronger one on paid tiers. The Model: badge in each response tells youwhich one answered.
• Analyses run on DebugAI's servers. The error text and any snippet you passare sent there. Privacy policy: debugai.io/privacy.

Troubleshooting

• "authentication failed": key missing or wrong. Check the env block inyour client config or ~/.debugai/config.json, restart the client. Keysstart with dbg_.
• Nothing happens on npx @debugai/mcp: correct. It's a stdio server thatwaits for an MCP client to speak first. Run npx @debugai/mcp --help toverify the install.
• Timeouts: deep analyses can take up to 90s. If your client has its owntool timeout, raise it above that.

Development

npm install
npm test        # builds, then runs unit + spawned-process e2e tests

MIT © DebugAI