MCP CLI

@debugai/mcp is the DebugAI MCP server and the command that sets it up. It needs Node.js 18.14.1 or newer. Run any command through npx:

npx -y @debugai/mcp <command>

Or install it once and call it as debugai-mcp:

npm i -g @debugai/mcp@latest
debugai-mcp <command>

A global install does not update itself. Run the install command again when a new version ships. npx -y @debugai/mcp --help prints the same list as this page.

CommandsCopy Anchor Link

setupCopy Anchor Link

npx -y @debugai/mcp setup

Runs login, then install, then doctor. If a key is already stored, login is skipped and it prints ✓ Already signed in — skipping login (use --force to re-link).

Flags after setup go to install. --force signs you in again even with a key stored.

npx -y @debugai/mcp setup --client=cursor

loginCopy Anchor Link

npx -y @debugai/mcp login

Starts a browser sign-in. It prints Sign in to DebugAI, a code in a box, and Confirm that code at followed by the address, opens your browser on that address, then waits: Waiting… the code expires in 10 minutes. Ctrl-C to cancel.

On macOS it opens the browser with open, on Windows and WSL with rundll32 url.dll,FileProtocolHandler, and on Linux with xdg-open. It opens nothing when the CI variable is set or on Linux with no display. Then it prints the address for you to open on any device.

Once you confirm the code in the browser:

✓ Signed in as you@example.com (free tier).
  Key saved to /home/you/.debugai/config.json. Every MCP client on this machine reads it.

  Next: npx -y @debugai/mcp install (wires up the MCP clients you have)

With a working key already stored, login says ✓ Already signed in as your email and stops. When it fails:

logoutCopy Anchor Link

npx -y @debugai/mcp logout

Deletes the key from the config file and prints ✓ Stored key removed from the file's path. If DEBUGAI_API_KEY is still set in your environment, it warns that the variable takes priority over the file.

statusCopy Anchor Link

npx -y @debugai/mcp status

Prints the API base, the key in masked form and where it came from (the config file or DEBUGAI_API_KEY), and the account and plan it belongs to. It exits with code 1 when there is no key, or when the key is rejected or the API cannot be reached.

installCopy Anchor Link

npx -y @debugai/mcp install

Adds DebugAI to every MCP client it detects on this machine. A client counts as detected when its config file or its app folder exists.

For each client it prints one of:

• ✓ Cursor — added to the file, or updated in the file, followed by backup: and next: lines. The backup sits next to the original as <file>.debugai-backup-<timestamp>, and next: says how to make that client pick DebugAI up.
• ✓ Cursor — already configured, nothing to change
• ✗ Cursor — could not parse (…) — left untouched, followed by merge this in by hand: and the entry to paste.

It ends with ✓ Key already stored — restart the clients above and you are done., or with No API key stored yet — run npx -y @debugai/mcp login to finish. when you have not signed in. --dry-run ends with Dry run — nothing was written. When no client is found it prints No MCP clients detected on this machine. and the full list.

Before it changes a file, it copies it. It keeps every other setting in the file, keeps the file's permissions (and the link, if the file is a symlink), and replaces the file in one atomic step. JSON cannot hold comments, so a config file with comments loses them. install says when that happened, and the backup still has them; --dry-run tells you beforehand.

uninstallCopy Anchor Link

npx -y @debugai/mcp uninstall

The same as install --remove --all. It removes the DebugAI entry from every supported client, including the VS Code one and any Claude Code entries scoped to a single directory. Each file is backed up first. Your stored key stays; run logout to remove it too.

doctorCopy Anchor Link

npx -y @debugai/mcp doctor

It prints its checks under four headings: Runtime, Account, API and MCP clients. These count as problems:

• Node is older than 18.14.1.
• No key is stored, or the key does not start with dbg_.
• The key does not authenticate against the API, or the API cannot be reached.

These are warnings, which it prints with the fix but does not count:

• Outside Windows, the config file can be read by other users. The fix is chmod 600 on the file.
• A detected client has no DebugAI entry. The fix is debugai-mcp install --client= and the client's ID.
• An entry runs @debugai/mcp with no version, so npx can run an old copy.
• A Claude Code entry works in one directory only.
• A client config holds an API key in plain text, which keeps failing after you rotate your key.

It ends with ✓ Everything checks out., or with the count, such as ✗ 1 problem to fix., and then exits with code 1. Each problem line has a hint under it, usually the command that fixes it.

hookCopy Anchor Link

npx -y @debugai/mcp@latest hook

You do not run this yourself. Claude Code runs it after a shell command fails, once you add it as a PostToolUseFailure hook. Setup: Claude Code.

• It acts only on Bash and PowerShell tool failures with a non-zero exit code that were not interrupted, and only when the output has at least 12 characters.
• It looks the output up in this project's memory: the same lookup as lookup_error, with no model call, and it does not count against your plan.
• It prints only when memory has something: a stored fix, or a fix this project reported as failed. Its answer goes to the agent beside the failure, cut to 9,000 characters.
• It reads the key login stored, or DEBUGAI_API_KEY, and never starts a sign-in.
• It waits at most 5 seconds for its input and 8 seconds for the lookup, and always exits with code 0, so it never blocks the agent.
• It sends the failed command's output, up to 3,000 characters, and the project ID. The command line is not sent.

Running the serverCopy Anchor Link

npx -y @debugai/mcp

Runs the MCP server on stdio and waits for a client to speak first, so in a terminal it looks like nothing is happening. That is correct. It logs to stderr only, starting with a line like [debugai-mcp] v2.7.0 connected on stdio, or a note that no key is stored yet. Without a key, the first tool call hands your agent a sign-in link, and nothing needs restarting once you confirm it.

Clients and the files install writesCopy Anchor Link

"AppData" below is %APPDATA% on Windows (by default ~/AppData/Roaming), ~/Library/Application Support on macOS, and $XDG_CONFIG_HOME or ~/.config on Linux.

The entry is the same everywhere except Zed and VS Code, and it never contains your key:

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

Keep the @latest. Without a version, npx runs the first copy it finds, and an old global install wins over the newest release.

Where the key livesCopy Anchor Link

login writes the key to one file, and every MCP client on the machine reads it from there:

{
  "api_key": "dbg_…"
}

Outside Windows the file is created with mode 0600 and its folder with 0700, so only your user can read it. The file can also hold api_base. Set DEBUGAI_CONFIG_PATH to keep it somewhere else.

Environment variablesCopy Anchor Link

Environment variables win over the config file.

RelatedCopy Anchor Link

• AI agents quickstart
• MCP tools: what the server gives your agent.
• The MCP server: when it does not connect.