mcp-remote
An adapter that connects an MCP client limited to local stdio servers to a remote MCP server over HTTP or SSE, with authorization
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- Forwards traffic and credentials to whatever remote server you configure
- Stores and refreshes OAuth tokens locally
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mcp-remoteDetects the agents on your machine, checks the risk and pins the version.
Other ways to install
Install the tool
npm install -g mcp-remoteAdd an mcpServers entry to the client config with command npx and args mcp-remote plus the remote server URL. For token auth add a --header with an Authorization header.
Other ways from the author
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": ["mcp-remote", "https://remote.mcp.server/sse"]
}
}
}Replace the URL with your remote server address. For a token add --header and Authorization: Bearer <token> to args.
This is third-party code. Review the repository files before installing.
What it does
mcp-remote is a bridge between an MCP client that only speaks local stdio and a remote MCP server over HTTP or SSE. It runs through npx inside the mcpServers config and handles the OAuth flow, token refresh and local token storage for you. It supports custom headers and a header file, per-resource session isolation via RFC 8707, extra authorization parameters, callback port and host selection, timeouts, keep-alive, proxy support and filtering of the remote server's tools. It fills the gap until popular clients reach remote authorized servers on their own.
Who it is for. For users of Claude Desktop, Cursor, Windsurf and other clients who need to reach a remote MCP server that requires authorization.
Good fit when
- Your client only supports local stdio servers but you need a remote one
- The remote server needs OAuth or custom headers
- You need to keep several accounts of one server in separate sessions
Not a fit when
- Your client already connects to remote authorized servers directly
- You need an actual MCP server rather than an adapter to one
Example request
Connect me to this remote MCP server over its URL using mcp-remoteLimitations
It is an adapter, not a server: it only forwards traffic to a remote server and passes it your credentials and headers. OAuth tokens are stored locally in the ~/.mcp-auth directory. Some clients mishandle spaces in args, and the README gives workarounds via environment variables or a header file. Reaching a given remote server depends on that server.
How to disable. Remove the server entry from the mcpServers block in your client config. The auth cache lives in the ~/.mcp-auth directory.
Security check
- Forwards traffic and credentials to whatever remote server you configure
- Stores and refreshes OAuth tokens locally
README in short
The README explains why the adapter exists: most clients only work with local stdio servers and cannot yet run OAuth against remote ones. mcp-remote runs through npx and closes that gap. The docs cover the flags in detail: custom headers and a header file, the --resource flag for session isolation, extra authorization parameters, callback port and host, timeouts, keep-alive, proxy support and tool filtering. It also documents workarounds for clients that mangle spaces in args.
FAQ
Is this a standalone MCP server?
No. It is an adapter that connects an stdio client to a remote server over HTTP or SSE and runs the authorization for it.
Where do the tokens go?
OAuth tokens and session data are stored locally in the ~/.mcp-auth directory, separately for each combination of URL, resource and headers.
Related
Open-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
An open source coding agent for the terminal and desktop with build and plan modes
Open prompt library with a Claude Code plugin, MCP server and CLI: search, fetch and improve prompts and skills from an agent