mcp-remote: use a remote MCP server in any app

When you need it, and when you do not

Every MCP Shelf server page uses it for you where it is needed: the Claude Desktop tab of a remote server that needs a key header shows an mcp-remote config.

The basic config

Put the server URL after the package name. The -y stops npx from waiting for you to confirm the download, which an app cannot do.

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

The first time your app starts it, mcp-remote opens your browser so you can sign in to the service. It saves the tokens in ~/.mcp-auth and reuses them, so you only sign in again when they expire. It needs Node.js 18 or newer, and apps such as Claude Desktop use the Node on your system path, not one you installed somewhere else.

Sending an API key header

For servers that take a key instead of a browser sign-in, pass --header. Keep the key itself in env and refer to it by name:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.example.com/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_TOKEN" }
    }
  }
}

Anyone on the same machine can read process arguments. To keep a key out of them, put one Name: value line per header in a file and pass --header-file /full/path/headers.txt instead.

Flags worth knowing

The full list is in the mcp-remote README, maintained by its author on GitHub.

When sign-in or the connection keeps failing

1. Quit your app completely, then delete the saved sign-ins with rm -rf ~/.mcp-auth (on Windows, delete the .mcp-auth folder in your user folder). Open the app again and sign in fresh.
2. Check node --version in a terminal says 18 or higher.
3. Behind a company VPN or proxy, point Node at your company certificate with an env entry: "NODE_EXTRA_CA_CERTS": "/path/to/company-ca.pem".
4. Add --debug and read the log in ~/.mcp-auth.
5. Still stuck? Test the URL on its own with MCP Inspector. If it fails there too, the problem is the server or your account, not mcp-remote.

Servers on MCP Shelf with a URL

Questions