Other MCP clients
Add DebugAI to any MCP client that runs local servers, with one sign-in and one config entry.
Any MCP client that can start a local server over stdio can run DebugAI. setup writes the config for Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI and Cline, and for VS Code when you ask. For any other client, sign in once and add the entry yourself.
You need Node.js 18.14.1 or later. node -v prints your version.
Sign in once
npx -y @debugai/mcp loginYour browser opens on a short code to confirm (free account, 10 debugs a day, no card). On a machine with no browser, login prints the address instead, and you open it on any device. When it is done:
✓ Signed in as you@example.com (free tier).The key is saved to ~/.debugai/config.json with 0600 permissions. Every client on the machine that starts the server reads it from there, so you never paste it into a client config.
For CI or a machine that cannot open the sign-in page, paste a key from the Settings tab of your dashboard instead:
npx -y @debugai/mcp login --key dbg_your_keyAdd the entry
The command is npx and the arguments are -y and @debugai/mcp@latest. Most clients list servers under mcpServers in a JSON file, like this:
{
"mcpServers": {
"debugai": {
"command": "npx",
"args": ["-y", "@debugai/mcp@latest"]
}
}
}Keep the @latest. Without a version, npx runs the first copy of the package it finds, and an old global install wins over the newest release. That has happened: one agent ran a whole session on a copy from July that sent no project, so project memory was off for every call. doctor warns about an entry with no version, for the clients it knows.
Restart the client and check it works
Restart or reload the client so it starts the server. Then hand its agent an error and ask for the lookup by name:
Use the debugai lookup_error tool on this error: TypeError: Cannot read properties of undefined (reading 'name')lookup_error makes no model call and does not count against your daily limit, so this check is free.
You'll know it worked when
The agent calls lookup_error and gets back a line like Not seen before in this project (shop). Call debug_error with the full error for an analysis. The name in brackets is your project's folder.
Running npx -y @debugai/mcp yourself in a terminal prints one line, starting [debugai-mcp], and then waits. That is correct: it is a stdio server, waiting for a client to speak first. To check the install instead, run npx -y @debugai/mcp --help.
Keep the key out of client configs
Setting DEBUGAI_API_KEY in a client's env block works, and it wins over the stored key. It is still the wrong place for it. Client configs get committed and pasted, and after you rotate your key, the old one in that file keeps outranking the new stored one, so the client keeps failing. doctor flags a key written in plain text in a known client's config. Use login, and leave env out of the entry.
Environment variables
| Variable | Default | What it does |
|---|---|---|
DEBUGAI_API_KEY | none | Your key. Wins over the key login stored. |
DEBUGAI_API_BASE | DebugAI production | The API the server talks to, for a staging or self-hosted setup. Falls back to api_base in the config file. |
DEBUGAI_TIMEOUT_MS | 150000 | The deadline for debug_error, in milliseconds. lookup_error waits 8 seconds and report_outcome 15, whatever this says. The hook ignores it. |
DEBUGAI_CONFIG_PATH | ~/.debugai/config.json | A different config file. |
If your client has its own timeout for tool calls, set it above 150 seconds, the server's own deadline for debug_error. Otherwise the client can give up on an answer the server is still waiting for.
The remote server
DebugAI also runs a remote server at https://mcp.debugai.io/mcp, with OAuth sign-in and nothing to install. Today it is the server behind the ChatGPT and Codex plugin: set those up from ChatGPT and Codex. It sees only the text an agent passes in and cannot read your files. For any other client, use the local server on this page, which reads the source files a stack trace names inside your project.
Next
- Work with your agent: the lookup, debug and report loop, and how to point an answer at the right project.
- MCP server troubleshooting:
doctoroutput, sign-in from inside a chat, and the errors an agent can get back.