AI agents quickstart
One command signs you in and adds DebugAI to Claude Code, Cursor, Windsurf and every other MCP client it finds.
DebugAI runs as an MCP server, so your coding agent can call it the moment a command fails. The agent gets three tools: lookup_error checks your project's memory for free, debug_error finds the root cause and returns ranked fixes, and report_outcome records whether a fix worked.
You need Node.js 18.14.1 or later. Check with node -v.
The setup finds and configures these clients: Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI and Cline. For VS Code's own agent mode, install the extension instead: it registers the server for you (details).
Run setup
npx -y @debugai/mcp setupIt does three things, in order:
- Signs you in. It prints a short code and opens your browser. Confirm the code on debugai.io (free account, no card). The key is saved to
~/.debugai/config.jsonwith file mode 0600, and every MCP client on this machine reads it from there. - Adds DebugAI to every client it finds. Each config file is backed up before the first change, and your other settings are kept. Your key is never written into a client's config.
- Checks the result with
doctor: your Node version, your key, whether the API answers, and which clients are wired up.
To see what it would write before it writes anything:
npx -y @debugai/mcp install --dry-runYou'll know it worked when
The last line doctor prints is ✓ Everything checks out.
Restart your client
Each client picks up a new server differently. setup prints the step for every client it changed, and here they are in one place:
| Client | What to do |
|---|---|
| Claude Code | Start a new session, or run /mcp to reconnect. |
| Claude Desktop | Quit it completely and reopen it. Closing the window is not enough. |
| Cursor | Nothing. It picks the server up on its own; Cursor Settings, MCP shows a green dot. |
| Windsurf | Open Settings, MCP and press refresh. |
| Zed | Nothing. Zed reloads settings on save, and the server appears in the agent panel. |
| Gemini CLI | Restart the session. |
| Cline | Open the Cline panel, then MCP Servers. It reconnects without restarting VS Code. |
Hand your agent an error
Ask your agent to run something that fails and to use DebugAI on it, or paste an error and say "debug this with DebugAI". For example, with the project from Your first debug:
Run python main.py. If it fails, use DebugAI to find the root cause before you change anything.debug_error reads the files the stack trace names, from inside your project only, and answers with a root cause and up to three ranked fixes. Each fix says whether a mechanical check verified it.
You'll know it worked when
Your client shows a call to the debug_error tool from the debugai server, and the agent's answer names a root cause and a file and line in your project.
Tell your agent when to use it
Agents follow their instructions file. Add this rule to CLAUDE.md, .cursorrules or your client's equivalent, so the agent checks memory first and reports back after a fix:
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.lookup_error makes no model call and does not count against your daily limit. Reporting outcomes is what lets the next occurrence of the same error arrive with the fix that held. More in Work with your agent.
Skipped the sign-in?
The server still starts. The first tool call hands your agent a sign-in link and a code to pass on to you. Confirm the code in your browser, and the agent can call the tool again. The client does not need restarting.
Claude Code can look up every failed command
A hook runs lookup_error on each failed shell command, so Claude Code hears what your project's memory knows about that error before it starts guessing. It makes no model call and costs nothing. Setup is in Claude Code.
Undo it
npx -y @debugai/mcp uninstallThis takes DebugAI back out of every client config it can find. The backups stay where setup put them.
Next
- One page per client, with the exact file each one uses: Claude Code, Cursor, Windsurf, Claude Desktop, Zed, Gemini CLI, Cline, other clients.
- The MCP server, when
doctorreports a problem. - MCP tools, every input and output.