Debugai MCP

@debugai/mcp

Give your coding agent a debugger instead of a grep loop.

Your agent hands an error to debug_error and gets back the root cause, the exact file and line, and up to 3 ranked fixes as ready-to-apply edits. Each fix is labeled with whether a mechanical check actually passed, so the agent knows which ones were checked and which are the model's own estimate.

Before any of that, lookup_error asks your project's memory whether this error has happened here before and which fix held. It makes no model call and does not count against your limit, so an agent can afford it on every failure. In Claude Code a hook runs it for every failed command without the agent having to remember.

Auto-configures Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI, and Cline. Works in any other MCP client with a manual entry. Node 18.14.1 or later.

New in 2.7.0: machine-applicable edits now name the file their code is actually in, the tools say to call them the moment something fails rather than waiting for you to paste an error, and a server that has fallen behind says so once per session instead of in the middle of every diagnosis. A server started in your home folder, a folder above it or the filesystem root no longer treats that as a project: it reads no local files until the agent names a projectRoot. See the changelog.

If a fix does not work, tell me and I will fix it. The fixes that did not work are how most of this release got written. [Dashboard → Messages](https://debugai.io/dashboard?tab=messages&src=npm-readme), with the error you sent and what the fix did instead. It reaches the person who builds this.

Setup

npx -y @debugai/mcp setup

That is the whole thing. It signs you in through your browser (no key to find or copy), writes the config for every MCP client it finds on this machine, then checks that all of it actually works.

Restart the clients it names and your agent has the tools.

Prefer to read first? debugai.io/start?src=npm walks the same thing per client.

What that command does to your machine

Worth knowing before you run something that edits your editor config:

• Signs you in with a short code you confirm in the browser. Free account, 10 debugs a day, no card.
• Stores your key in ~/.debugai/config.json with 0600 permissions. That is the only file that ever holds it.
• Adds a debugai entry to the config of each MCP client it detects. Every file is backed up first ( .debugai-backup- ), every other setting in the file is preserved, and a file it cannot parse is left alone and reported instead. One caveat stated plainly: if your config contains comments, the rewrite drops them, because JSON has nowhere to put them. install writes first and tells you afterwards, and the backup still has them. install --dry-run tells you before anything is written.
• Skips VS Code by default, because the DebugAI extension already registers this server there and a second entry would show every tool twice. install --client=vscode does it anyway if you want the server without the extension.
• Never writes your key into a client config. Client configs get committed to repos. Keys should not.

Preview it without writing anything:

npx -y @debugai/mcp install --dry-run

Undo all of it:

npx -y @debugai/mcp uninstall   # removes the entry from every client config

npx -y @debugai/mcp logout # removes the stored key

Commands

npx -y @debugai/mcp install --list prints every supported client, where its config lives on your OS, and whether DebugAI is already in it.

Signing in from inside a chat

If your agent calls a DebugAI tool before you have signed in, the tool answers with a short code and a URL instead of an error. Confirm it in the browser, tell the agent to try again, and the call goes through. No config editing, and no client restart, because the key is re-read on every call.

The tools

The loop they are built for: a command fails, lookup_error answers from memory in under a second, a confirmed fix is applied and the command re-run. When memory has nothing, debug_error does the analysis. Either way report_outcome says what happened, which is what the next lookup reads.

lookup_error

Has this project seen the error before, and what held? (2.6)

It is two small database reads and no model call, so it is free: it does not count against the debug limit (a separate, generous rate limit keeps it honest). It returns how many times the error was seen in this project and when, the stored fix and what state it is in, and fixes this project recently reported as failed:

• confirmed: somebody applied it and said it worked. The answer says whether a live session watched the error stop or it was only accepted, because those are different amounts of evidence.
• unproven: it was applied and the error has come back once since. Check it against the code as it is now.
• anti-pattern: the error came back two or more times after it. The answer names it as the thing not to do.

A miss says so and points at debug_error. The text of the error is prepared exactly as a debug prepares it, credentials redacted first, so a lookup and a debug of one failure read the same memory row. A lookup writes nothing: it is not a debug and not a sighting.

debug_error

Give it an error, get an analysis.

Returns the root cause, up to 3 fixes ranked by confidence, the detected framework, and whether the answer came from cache. Each fix also carries, where derivable: edits (exact old/new strings your agent's edit tool can apply directly), unified_diff, and verify_with, the check to run after applying. With reproCommand that check is your command and the result you said to expect; without it, a syntax-level check. It never writes to your files and never runs your reproduction. Applying a fix is your agent's call, and yours.

An error longer than the 3,000 characters the API accepts is cut rather than refused: the start (where JavaScript, Java and .NET print the error) and the end (where Python prints it) are kept, the middle goes, and the answer says so. The same cut is made by lookup_error and the hook, so all three read one memory row for one failure. (2.6)

A footer on every answer names the project it was filed under, says when memory was off for it and why, and gives the version of this server and the engine build that answered. A session running on an old copy can see that it is, and an answer can be traced to the code that produced it. (2.6)

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

It reads the source the trace names (2.2)

Paste a raw traceback and nothing else. This server runs on your machine, so it resolves the files in the stack trace and sends the relevant code along. Before 2.2 it could not, and an error pasted without code came back as *"Insufficient context for specific fix"* at 20% confidence. That was the common case, not the edge one.

The response names every file it read (Read locally: src/api.ts, src/db.ts, and local_files_read in the structured payload), so a wrong guess is visible rather than silent.

Exactly what it will and will not read:

• Inside your project only. The boundary is your git repo root, or the working directory when that is not a repo. When that is your home directory, a folder above it or the filesystem root there is no boundary to read inside, so nothing local is read and the reply says so; pass projectRoot to name the project. It is checked *after* symlinks resolve, so a path in an error message cannot walk out of the project: ../../.ssh/id_rsa and a symlink pointing outside both fail the same check.
• Source files only, by extension allowlist (.ts .tsx .js .jsx .mjs .cjs .py .pyi .go .rs .rb .java .kt .kts .scala .groovy .gradle .php .cs .swift .dart .c .cc .cpp .h .hpp .ps1 .psm1 .psd1 .vue .svelte). .env, .pem, key files, dumps and images are not on it, so they are never candidates.
• Bounded: at most 3 files, none over 2 MB, and 50,000 characters in all. A large file is sent as a ±40-line window around the failing line rather than whole. Windowed blocks say so.
• **Vendored code is sk