Extensions/tools using openExternalUrl silently fail — OAuth flows broken for tools in terminal

[mvn-bachhuynh-dn]

ACP/Extension openExternalUrl silently fails — OAuth flows broken for tools running in code-server terminal

Summary

When CLI tools running inside a code-server terminal session use the ACP (Agent Communication Protocol) openExternalUrl capability to open an OAuth authorization URL in the user's browser, the request is silently dropped. No browser window opens, no error is returned to the caller, and no fallback mechanism is provided.

This breaks OAuth authentication for any MCP (Model Context Protocol) server that requires browser-based login, including:

• Atlassian Rovo MCP
• Cloudflare MCP
• Any OAuth 2.0 PKCE flow relying on localhost callback

Environment

• code-server: accessed via HTTPS reverse proxy (e.g., https://code.example.com)
• Host OS: Linux (Ubuntu)
• Client: macOS browser (Safari/Chrome)
• Tool: Kiro CLI 2.16.2 running in code-server's integrated terminal
• Protocol: ACP with openExternalUrl capability negotiated successfully

Reproduction Steps

1. Access code-server from a browser on macOS
2. Open integrated terminal
3. Run kiro-cli chat
4. Kiro negotiates ACP capabilities including openExternalUrl: true
5. Configure an OAuth-based MCP server (e.g., Atlassian)
6. Trigger authentication — Kiro sends _kiro/openExternalUrl with the OAuth URL
7. Nothing happens — no browser opens, no error surfaces

Expected Behavior

One of:

1. code-server forwards the openExternalUrl request to the client browser and opens the URL in a new tab
2. If opening is not possible, code-server returns an error/rejection so the calling tool can fall back (e.g., print the URL for manual copy)
3. code-server provides a notification/toast with the URL that the user can click

Actual Behavior

• The ACP capability openExternalUrl is advertised as supported during handshake
• The actual openExternalUrl request is received but silently dropped
• No browser opens on the client machine
• No error is returned to the requesting tool
• The tool (Kiro) waits for an OAuth callback that never arrives, eventually timing out

Analysis

code-server's integrated terminal runs on the remote host. When a tool calls openExternalUrl, there are two issues:

1. No browser on remote: The remote Linux host typically has no display server or browser. xdg-open or equivalent fails silently.
2. No forwarding to client: Unlike VS Code Remote SSH (which forwards vscode.env.openExternal to the local VS Code instance), code-server does not appear to relay external URL open requests to the connected browser client.

The VSCODE_PROXY_URI environment variable is set (e.g., https://code.example.com/proxy/{{port}}/), but this only handles port forwarding for HTTP services, not arbitrary URL opening.

Suggested Solutions

1. Implement client-side URL forwarding: When openExternal / openExternalUrl is called, relay the request via WebSocket to the connected browser and open it in a new tab using window.open().
2. Return an error when forwarding is unavailable: Instead of silently dropping the request, return a rejection so tools can implement fallback behavior (displaying the URL for manual copy).
3. Show a notification: Display a toast/notification in the code-server UI with the URL as a clickable link, similar to how VS Code shows "open in browser" prompts for forwarded ports.

Impact

This affects any tool, extension, or CLI application running in code-server's terminal that needs to open a URL in the user's browser. OAuth flows for MCP servers are a prominent use case, but this also affects:

• Git credential helpers with browser-based auth
• Cloud CLI login flows (e.g., gcloud auth login, aws sso login)
• Any tool using xdg-open or equivalent

Workaround

For OAuth specifically with fixed localhost callbacks:

1. Configure the tool to use a fixed callback port
2. Set up SSH local port forwarding from the client machine to the remote host
3. Manually obtain and open the authorization URL (requires tool-specific patching or log inspection)

See related Kiro CLI issue for detailed workaround steps.

Labels

bug, feature-request, terminal, oauth, remote

[linear-code]

DEVEX-765

[mvn-bachhuynh-dn]

Update: Root Cause Clarified — Interaction Between $BROWSER, xdg-open, and ACP openExternalUrl

After further investigation, we identified the full picture of how browser-opening fails in code-server for different tools. This affects any CLI tool running in code-server's integrated terminal that needs to open a URL in the user's browser.

Three Browser-Opening Mechanisms and Their Behavior in code-server

Mechanism	Used By	Behavior in code-server Terminal
$BROWSER env var	Some CLI tools	code-server sets BROWSER=/usr/lib/code-server/lib/vscode/bin/helpers/browser.sh — this works and opens URL on client browser via --openExternal
xdg-open	CLI tools (Rust binary fallback)	Fails — no $DISPLAY on headless server, returns non-zero exit
ACP openExternalUrl	Extensions/agents (Kiro MCP OAuth)	Silently dropped — request received but never forwarded to client browser

Key Finding

code-server already provides a working mechanism to open URLs on the client browser: the browser.sh helper script (used via $BROWSER). It calls code-server --openExternal <url> which relays the request via WebSocket to the connected browser.

However, this mechanism is NOT connected to the ACP openExternalUrl capability. When an extension or agent communicates via ACP and requests openExternalUrl, the request goes through a different path that does not invoke browser.sh or --openExternal.

The Silent Failure Problem

The critical issue is that ACP openExternalUrl:

1. Is advertised as supported during capability negotiation (openExternalUrl: true)
2. Silently drops the request without error
3. Does not fall back to browser.sh / --openExternal
4. Does not return a failure to the caller

This means tools that rely on ACP cannot detect the failure and implement their own fallback (like printing the URL).

Impact on Users

Users who create xdg-open or $BROWSER wrappers to work around this issue should be warned:

• If your wrapper returns exit 0, tools with fallback behavior (like printing the URL on failure) will not trigger the fallback — they think the browser opened successfully
• This makes the situation worse: you lose both the auto-open AND the fallback URL display

Suggested Fix

Since code-server already has --openExternal working:

1. Connect ACP openExternalUrl to --openExternal: When the ACP handler receives an openExternalUrl request, invoke the same --openExternal mechanism that browser.sh uses
2. Return error on failure: If the WebSocket connection to the client is down or the request fails, return an error to the ACP caller so it can implement fallback behavior
3. Document the limitation: Until fixed, document that ACP openExternalUrl does not work and tools should use $BROWSER env var for opening URLs

Workaround for Users

Do NOT create custom wrappers. Instead:

• For tools that check $BROWSER: They already work in code-server terminal (code-server auto-sets $BROWSER to browser.sh)
• For tools that use xdg-open directly: Let it fail; well-designed tools print the URL as fallback
• For tools that use ACP openExternalUrl (like Kiro MCP OAuth): This requires tool-specific workarounds (see [CLI] MCP OAuth authorization URL not displayed/accessible when running Kiro CLI inside code-server (remote environment) kirodotdev/Kiro#10817 for detailed steps)

Environment

• code-server accessed via HTTPS reverse proxy
• Host: Linux (headless, no display server)
• Client: macOS browser
• $DISPLAY: empty
• $BROWSER: /usr/lib/code-server/lib/vscode/bin/helpers/browser.sh (set by code-server)

Related: kirodotdev/Kiro#10817

[impartshadow]

This is a capability-contract false positive: code-server advertises a browser-opening capability that its remote runtime cannot actually fulfill.

My root-cause hypothesis is that capability negotiation checks only whether the ACP method is recognized, not whether a live browser client can receive and acknowledge it. The strongest evidence is that “The ACP capability openExternalUrl is advertised as supported during handshake” while “the actual openExternalUrl request is received but silently dropped.” On a headless Ubuntu host, any fallback through xdg-open is also non-viable, leaving Kiro waiting on a callback for an action that never occurred.

The deterministic check belongs at the ACP-to-browser transport boundary: after _kiro/openExternalUrl is received, assert that either an attached browser session acknowledges dispatch of the exact URL, or the request returns a typed rejection before the RPC deadline. A contract test should negotiate openExternalUrl: true, disconnect or omit the browser transport, invoke the method, and fail if the result is success or no response; advertising the capability must itself require a usable client-side handler.

I cannot confirm whether the drop occurs in code-server’s ACP adapter, URI opener service, or browser transport without an RPC trace showing the negotiated capability, handler selection, and response path.

Advisory SFA-2026-67FD702AEF · Full redacted write-up: https://impartshadow.github.io/echo-site/failure-cases/extensions-tools-using-openexternalurl-silently-fail-67fd702aef.html — I triage one of these in public every day.
If this diagnosis is useful, react 👍 to this comment; if it is wrong, react 👎 — I use the verdict to choose what I investigate next.