Set up with other agents

Connect opencode, Gemini CLI, Amp, Zed or Windsurf to Unhandled with one command or one config entry.

Every agent here connects to https://unhandled.net/mcp/x/debug, the debug toolset. npx @unhandled/cli mcp install --agent <agent> runs the agent's own command where one exists. Otherwise it merges the unhandled entry into the config file, keeps every other key and backs the file up first. Add --print to only print what it would run or write.

Agent	`--agent`	Fix and watch from the CLI
opencode	`opencode`	Yes
Gemini CLI	`gemini`	Yes
Amp	`amp`	Yes
Zed	`zed`	No
Windsurf	`windsurf`	No

~/.config/opencode/opencode.json

{
  "mcp": {
    "unhandled": {
      "type": "remote",
      "url": "https://unhandled.net/mcp/x/debug",
      "enabled": true
    }
  }
}

More options are in the opencode MCP servers docs.

Terminal

gemini mcp add --transport http --scope user unhandled https://unhandled.net/mcp/x/debug

Or add it to ~/.gemini/settings.json:

~/.gemini/settings.json

{
  "mcpServers": {
    "unhandled": {
      "httpUrl": "https://unhandled.net/mcp/x/debug"
    }
  }
}

More options are in the Gemini CLI MCP servers docs.

Terminal

amp mcp add unhandled https://unhandled.net/mcp/x/debug

Or add it to ~/.config/amp/settings.json:

~/.config/amp/settings.json

{
  "amp.mcpServers": {
    "unhandled": {
      "url": "https://unhandled.net/mcp/x/debug"
    }
  }
}

More options are in the Amp MCP docs.

~/.config/zed/settings.json

{
  "context_servers": {
    "unhandled": {
      "url": "https://unhandled.net/mcp/x/debug"
    }
  }
}

More options are in the Zed MCP docs.

Windsurf is now Devin Desktop, which reads ~/.config/devin/mcp_config.json and imports the older ~/.codeium/windsurf file.

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "unhandled": {
      "serverUrl": "https://unhandled.net/mcp/x/debug"
    }
  }
}

More options are in the Devin Desktop MCP docs.

Any other client that supports remote MCP servers with OAuth works with the same URL. See Connect a client.