LabscoMCP early access ↗
punkpeyeMCP SERVER

MCP Remote

Connect a client that only speaks stdio to a remote MCP server, including the OAuth flow — one line in the config, removable the day your client supports remote servers natively.

by punkpeye ↗MCP Plumbing: Proxies, Registries & InspectorsCommunity

LABSCO SUMMARY

The stopgap between remote MCP servers and clients that cannot reach them yet.

It is meant to be deleted: the moment your client supports authorized remote servers directly, the line comes out of the config. Until then it is what lets a stdio-only client use a server that lives on the web.

What it is

A bridge, not a server of its own. Most MCP clients today only launch local stdio servers; this stands in as that local process and forwards everything to a remote HTTP or SSE server, handling the authorization flow on the way.

What you get

  • The standard one-liner: npx mcp-remote https://<your-remote-mcp-server>/sse in the command and args of any client that takes them — Claude Desktop, Cursor and Windsurf all use the same shape
  • Custom headers with --header, to pass a bearer token or bypass the OAuth flow entirely
  • Isolated sessions per instance with --resource, so two tenants of the same remote server keep separate OAuth sessions and token storage; it is sent as the RFC 8707 resource indicator on the authorization, token and refresh requests alike
  • --disable-resource-parameter for authorization servers that reject it outright, such as Microsoft Entra ID v2
  • Transport strategies with --transport: http-first (the default, falling back to SSE on a 404), sse-first, http-only and sse-only
  • Static OAuth client metadata and client information via --static-oauth-client-metadata and --static-oauth-client-info, for servers that expect pre-registered clients rather than dynamic registration
  • --ignore-tool with wildcard patterns, filtering tools out of tools/list responses and blocking calls to them
  • Operational flags: --allow-http for trusted private networks, --enable-proxy to honour HTTPS_PROXY and NO_PROXY, --debug for verbose logs, and --silent
  • A client mode for diagnosis: npx -p mcp-remote@latest mcp-remote-client https://<your-remote-mcp-server>/sse runs the full authorization flow and lists the remote tools and resources

Requirements

Node 18 or higher — Claude Desktop uses your system Node even if a newer one is installed elsewhere. Credentials are stored under ~/.mcp-auth, or wherever MCP_REMOTE_CONFIG_DIR points; clearing that directory is the first fix for a stuck token exchange. The OAuth redirect listens on 3334 by default, changeable by passing a port after the server URL, with --host and --callback-path for the rest of the callback shape. Cursor, Codex-Cli and Claude Desktop on Windows do not escape spaces inside args, so pass a header as Authorization:${AUTH_HEADER} with no space and keep the space in the environment variable. Behind a VPN, NODE_EXTRA_CA_CERTS may need to point at your CA file. Glen Maddern wrote it; the repository has since moved to github.com/punkpeye/mcp-remote, which the npm package names as its home, and the README there credits him as the original author.

Setup effort

Get your endpoint, then paste it — add your endpoint to your client

See installation options