mcp-remote

by Glen Maddern

v0.1.38

MIT

Repository Docs npm

Featured Developer Tools

proxyoauthremoteutility

Summary

A proxy that lets local-only MCP clients connect to remote servers, handling OAuth and transport differences.

Features

Connect stdio-only clients to remote MCP servers
Handles OAuth flows and token storage
Supports custom headers and transport selection

Installation

Set up this MCP server in your favorite AI agent — copy a ready-made configuration below.

Any MCP-compatible agent

Most agents (Claude, Cursor, Windsurf, VS Code, and more) read a standard mcpServers configuration.

Open your agent's MCP configuration file.
Merge the snippet below into it.
Restart the agent — the "mcp-remote" tools will be available.

{
  "mcpServers": {
    "mcp-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp"
      ]
    }
  }
}

Claude Code

Add the server with a single CLI command.

claude mcp add mcp-remote -- npx -y mcp-remote https://example.com/mcp

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config).

{
  "mcpServers": {
    "mcp-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp"
      ]
    }
  }
}

Cursor

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://example.com/mcp"
  ]
}

Windsurf

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://example.com/mcp"
  ]
}

VS Code

{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://example.com/mcp"
  ]
}

Description

mcp-remote is a small utility that solves a compatibility problem: many MCP clients only speak stdio to a local process, while a growing number of MCP servers are hosted and speak HTTP with OAuth.

What it does

It runs locally as a stdio server and proxies everything to a remote HTTP or SSE endpoint, handling the parts the client cannot:

OAuth authorisation flows, opening a browser for consent and storing the resulting tokens
Token refresh so a connection does not silently expire
Transport negotiation between streamable HTTP and SSE
Custom headers for servers using API keys instead of OAuth

Why you will end up needing it

Most vendor-hosted MCP servers — the ones you connect to with a URL rather than install — are remote. If your client does not yet support remote servers natively, mcp-remote is the bridge, and it is what most setup instructions tell you to use.

Setup

Add it as a command with the remote URL as its argument: npx -y mcp-remote https://example.com/mcp. Widely used and effectively a standard piece of MCP plumbing.