How to Fix: Broken “Open in Vscode” Links on Linux

If you are setting up an MCP (Model Context Protocol) server or authenticating a new tool in VS Code or Cursor, you might run into a wall: the browser tries to redirect you to a vscode:// or cursor:// URL, but nothing happens.

Linux doesn’t automatically know how to handle these custom protocol schemes. Here is the 2-minute fix to get your authentication flow working.

The Problem

When you click “Authorize,” the service sends a callback like this:

cursor://something.cursor-mcp/oauth/callback?code=...

Your system sees vscode:// or cursor:// and doesn’t know which application should “catch” that link.

The Solution: Register a Custom Mime Handler

1. Create a Desktop Entry

We need to create a definition file so the system recognizes VS Code or Cursor as a valid target for URLs. Open your terminal and create this file:

vim ~/.local/share/applications/cursor-handler.desktop

For VS Code:

vim ~/.local/share/applications/vscode-handler.desktop

Paste the following content (making sure to update the Exec path):

[Desktop Entry]
Name=Cursor Handler
# IMPORTANT: Replace the path below with the actual path to your Cursor AppImage or binary
Exec=/home/YOUR_USER/Applications/cursor.appimage --open-url %u
Type=Application
Terminal=false
MimeType=x-scheme-handler/cursor;

For VS Code it would be similar:

[Desktop Entry]
Name=VSCode Handler
# IMPORTANT: Replace the path below with the actual path to your VS Code binary
Exec=/usr/bin/code --open-url %u
Type=Application
Terminal=false
MimeType=x-scheme-handler/vscode;

2. Register the Scheme

Now, tell the system that VS Code and Cursor is the default handler for any link starting with vscode:// and cursor:// respectively.

xdg-mime default vscode-handler.desktop x-scheme-handler/vscode

and

xdg-mime default cursor-handler.desktop x-scheme-handler/cursor

3. Update the Database

To make sure the desktop environment sees the change immediately, run:

update-desktop-database ~/.local/share/applications

Testing the Fix

You don’t need to trigger the whole OAuth flow again to test it. Just run this in your terminal:

xdg-open "cursor://test"

# or

xdg-open "vscode://test"

If VS Code or Cursor pops to the front or opens up, you’re good to go. You can now go back to your browser, click that “Authorize” button again, and the handshake will complete automatically.

Why this happens

Most Linux distributions use xdg-open to decide how to handle files and links. By creating the .desktop file with the x-scheme-handler/vscode (or x-scheme-handler/cursor) MimeType, you are effectively plugging VS Code or Cursor into the system’s “switchboard.”

Bonus Tip: Since you’re already in the terminal using Vim to tweak your configuration, you might want to check out my guide on how to enable the clipboard in Vim to make copy-pasting between your browser and terminal seamless.