@abluva/mcp-remote

Abluva-maintained fork of mcp-remote — a stdio proxy that connects MCP clients (Claude Desktop, Cursor, etc.) to remote MCP servers with OAuth.

Use this package when upstream mcp-remote hangs on auth, drops mid-session re-login, or refuses OAuth callbacks on localhost.

📄 Full fork changelog, upstream issue/PR mapping, and version history: ABLUVA-FORK.md

Why Abluva maintains this fork

Upstream mcp-remote is the de facto OAuth bridge for stdio-only MCP clients. Several critical OAuth bugs remain open on geelen/mcp-remote — especially mid-session token expiry, Claude Desktop hangs, and localhost callback connection refused.

@abluva/mcp-remote merges:

• jacopoc’s unmerged re-auth branch (PR #213)
• Selected open upstream PRs (#297, #290, #302, #262 partial)
• Abluva production fixes for MCP gateway OAuth (callback server lifetime, auto ports, Hub logout re-auth)

Quick start (Claude Desktop)

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "-y",
        "@abluva/mcp-remote@latest",
        "https://your-mcp-gateway.example/mcp-connect/<catalog-id>"
      ]
    }
  }
}

Direct stateless server (MCP 2026-07-28, bypass gateway):

{
  "mcpServers": {
    "sql-sandbox-v2": {
      "command": "npx",
      "args": [
        "-y",
        "@abluva/mcp-remote@latest",
        "--protocol",
        "2026-07-28",
        "--allow-http",
        "http://127.0.0.1:8095/mcp/v2"
      ]
    }
  }
}

Protocol modes (--protocol)

• -y — required for Claude (non-interactive npx install).
• Callback port — optional third argument; omitted by default (auto-selected per server URL since v0.1.40).
• After first install or upgrade: rm -rf ~/.mcp-auth then restart Claude (Cmd+Q).

What we fixed (summary)

See ABLUVA-FORK.md for the complete table and version notes.

Branches & merges

geelen/mcp-remote @ v0.1.38 (main)
        │
        ├── jacopoc/implement-reauth-after-auth-error-on-send  →  mid-session re-auth (#213)
        │
        └── abluva-research/mcp-remote (main)
                ├── v0.1.39  OAuth re-auth + eager callback server
                ├── v0.1.40  Auto callback port / EADDRINUSE recovery
                ├── v0.1.41  #297, #290, #302
                ├── v0.1.42  Stale registration invalidation + port sync
                ├── v2.0.0   MCP 2026-07-28 stateless transport
                └── v2.0.1   Connect-time stale OAuth recovery

Not yet included

• PR #272 — respond to initialize immediately while OAuth runs in background (Claude 60s timeout). Requires larger proxy lifecycle change; tracked for a future release.

Local build

git clone https://github.com/abluva-research/mcp-remote.git
cd mcp-remote
npm install
npm run build
node dist/proxy.js https://your-gateway.example/mcp-connect/<id>

Upstream documentation

The sections below are inherited from upstream mcp-remote (usage, headers, transport strategies, etc.). For Abluva-specific OAuth behaviour, prefer ABLUVA-FORK.md.

mcp-remote (upstream)

Connect an MCP Client that only supports local (stdio) servers to a Remote MCP Server, with auth support:

Note: this is a working proof-of-concept but should be considered experimental.

Why is this necessary?

So far, the majority of MCP servers in the wild are installed locally, using the stdio transport. This has some benefits: both the client and the server can implicitly trust each other as the user has granted them both permission to run. Adding secrets like API keys can be done using environment variables and never leave your machine. And building on npx and uvx has allowed users to avoid explicit install steps, too.

But there's a reason most software that could be moved to the web did get moved to the web: it's so much easier to find and fix bugs & iterate on new features when you can push updates to all your users with a single deploy.

With the latest MCP Authorization specification, we now have a secure way of sharing our MCP servers with the world without running code on user's laptops. Or at least, you would, if all the popular MCP clients supported it yet. Most are stdio-only, and those that do support HTTP+SSE don't yet support the OAuth flows required.

That's where mcp-remote comes in. As soon as your chosen MCP client supports remote, authorized servers, you can remove it. Until that time, drop in this one liner and dress for the MCP clients you want!

Usage

All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the following config format:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

• If npx is producing errors, consider adding -y as the first argument to auto-accept the installation of the @abluva/mcp-remote package.

      "command": "npx",
      "args": [
        "-y",
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• To force npx to always check for an updated version, add the @latest flag:

      "args": [
        "-y",
        "@abluva/mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• To change which port @abluva/mcp-remote listens for an OAuth redirect (by default auto-selected per server URL since v0.1.40), add an additional argument after the server URL. If the port is unavailable, an open port will be chosen at random.

      "args": [
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• To change which host @abluva/mcp-remote registers as the OAuth callback URL (by default localhost), add the --host flag.

      "args": [
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• To allow HTTP connections in trusted private networks, add the --allow-http flag. Note: This should only be used in secure private networks where traffic cannot be intercepted.

      "args": [
        "@abluva/mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• To enable detailed debugging logs, add the --debug flag. This will write verbose logs to ~/.mcp-auth/{server_hash}_debug.log with timestamps and detailed information about the auth process, connections, and token refreshing.

      "args": [
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• To suppress default logs, add the --silent flag. This will prevent logs from being emitted, except in the case where --debug is also passed.

      "args": [
        "@abluva/mcp-remote",
        "https://remote.mcp.server/sse",
        "--silent"
      ]

• To enable an outbound HTTP(S) proxy for mcp-remote,