MCP tools

There are three DebugAI MCP servers, and they share one account and one set of plan limits:

Most of this page is the npm server. The other two are at the end, with what differs.

The loop the tools are built for: call lookup_error first, since it is free. If it has no confirmed fix, call debug_error. After trying a fix, call report_outcome, so the next time that error comes back in the project, memory knows what worked. See Work with your agent.

lookup_errorCopy Anchor Link

Look Up Error in Project Memory. Checks whether this project has seen the error before. No model call, and it does not count against your plan. Declared hints: readOnlyHint, idempotentHint, and openWorldHint: false.

It answers in plain text, such as Not seen before in this project (shop). Call debug_error with the full error for an analysis., or how many times it was seen and the fix confirmed for it. Fixes reported as failed in this project come under Tried in this project recently and reported as FAILED. Do not repeat these:.

The structured result has memory_enabled, memory_disabled_reason, memory_hit, memory_times_seen, memory_fix_state (none, confirmed, unproven or anti_pattern), memory_recurrences_after_fix, memory_verified_count, last_seen_at, stored_fix, refuted (each with at, rank, title and what_happened), project and mcp_version.

The API allows 300 lookups per 15 minutes per account.

debug_errorCopy Anchor Link

Debug Error. Finds the root cause of an error and returns up to three ranked fixes. It uses one debug from your plan and saves the analysis to your history and the project's memory. It does not change your files. Declared hints: readOnlyHint.

Before it calls the API, the server reads the source files the stack trace names, from inside the project only: at most 3 files, none over 2 MB, 50,000 characters in all, and a window of 40 lines either side of the error in a large file. It also sends the project's declared dependencies. Error text over 3,000 characters is cut, keeping its start and end. What leaves your machine has the full list.

What it returnsCopy Anchor Link

The text answer, in order:

1. ## Root Cause, then the cause in plain words.
2. ## Fixes, one block per fix, headed like **Fix 1 (82% confidence)** and the fix's title.
3. Under each fix, its verification line: ✓ Verified or ✗ Failed mechanical check (confidence capped) with the reason, or · Not verified, which says the confidence is the model's own estimate. Then the description, the code, _File:_ when the fix edits another file, and _Location:_.
4. What project memory knows about the error, when it knows something.
5. A footer of badges: the files it read locally, the model, whether project code was used (Codebase-aware: yes), whether the answer was cached, the framework, the project and where its root came from, Memory: off when memory is off, a note when the error text was cut, the server version and the engine build.
6. A reminder to call report_outcome with this answer's debugLogId.

The structured result:

Each fix has rank, title, description, confidence (0 to 100), and when they apply code, line_hint, file, verified (true, false or null, where null means nothing checked it), verification_reason, edits (exact file, old_string and new_string replacements), unified_diff, verify_with, verify_kind, verify_expect, syntax_check and previously_failed. A fix only carries edits when the change can be stated as an exact replacement. Verification explains the three states.

report_outcomeCopy Anchor Link

Report Fix Outcome. Records what happened after a debug_error answer. A confirmed fix is remembered for the project and handed back the next time the same error comes up there. Call it once per answer. Declared hints: idempotentHint.

The four results:

Use unused, not failed, when nothing of DebugAI's was run. A failed report marks a fix as tried and beaten.

It returns {"recorded": true, "result": …} and a sentence confirming what was saved.

Errors your agent can get backCopy Anchor Link

Every failure comes back as a tool result with isError set, a sentence the agent can relay, and a structured error_type:

quota_exceeded and monthly_ceiling tell the agent plainly not to retry, because the same call is refused until the limit resets. Plans and limits has the numbers.

The server inside the VS Code extensionCopy Anchor Link

VS Code 1.101 and later starts it on its own, under the name DebugAI, for agent mode. It has the same three tools with the same inputs. What differs:

• It uses the key from the extension's sign-in. If the key is rejected, it tells the user to run DebugAI: Set API Key from the Command Palette.
• Its project is the first folder open in VS Code. projectRoot is for an error from somewhere else. filePath does not name a project here.
• Its waits are fixed: 150 seconds for debug_error, 15 for report_outcome and 8 for lookup_error. DEBUGAI_TIMEOUT_MS does not apply.
• Its footer reads DebugAI MCP with the version and (VS Code), and its status link is https://debugai.io/status.

See VS Code agent mode.

The remote server, for ChatGPT and CodexCopy Anchor Link

https://mcp.debugai.io/mcp is a Streamable HTTP server. You sign in to your DebugAI account through OAuth, with Clerk as the sign-in service; ChatGPT or Codex offers the sign-in the first time a tool needs it. Setup: ChatGPT and Codex.

It sees only what each call carries. It cannot read your files or run code, so the agent has to pass the error, and any code, in the call.

What differs from the npm server:

• Projects are names. project is a short name such as billing-api, and memory is kept per name. A call that names none uses the project chatgpt, so ChatGPT and Codex share one memory unless you name projects.
• fileName is a file name or a relative path, not a full path from your computer.
• Sizes. errorText is cut to 3,000 characters, keeping its start and end, and codeSnippet to its first 20,000 characters. finalFix, newError and actualFix take up to 20,000 characters each. There is no toolFeedback.
• The engine gets 50 seconds to answer on this path.
• Reports wait for a real try. A report_outcome on an analysis less than 30 seconds old is refused, except unused, because nobody can have tried a fix that fast.
• get_profile returns an id that means nothing outside DebugAI, and your display name.

The structured results use camelCase. debug_error returns outcome (analysed or not_an_error), debugLogId, rootCause, fixes, memory, debugsLeftToday and repeated. Each fix has rank, title, confidence, explanation, verification (passed, failed or not_checked), verificationNote, code, file, location, edits, checkCommand and previouslyFailed. lookup_error returns project, seenBefore, timesSeen, lastSeenDate, fixState, storedFix, confirmation and failedFixes. report_outcome returns recorded, alreadyRecorded and result.

Declared hints: lookup_error and get_profile are read-only and idempotent. debug_error is neither, since it spends a debug and saves the analysis. report_outcome is idempotent and marked destructive, because a fix reported as worked replaces the one memory had.

RelatedCopy Anchor Link

• MCP CLI: installing the npm server and the Claude Code hook.
• Plans and limits
• Error memory