mcp-remote

To run multiple instances of the same remote server with different configurations (e.g., different Atlassian tenants), use the --resource flag. This isolates OAuth sessions so that each combination of server URL, resource, and custom headers maintains separate token storage.

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    },
    "atlassian_tenant2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant2.atlassian.net/"
      ]
    }
  }
}

Use mcp-remote to bridge MCP clients that only support local stdio transport (like Claude Desktop, Cursor, and Windsurf) to remote MCP servers using HTTP/SSE with OAuth support.

To use it, add mcp-remote as a command in your client's MCP configuration file, passing the remote server's SSE URL as an argument.

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

To add an MCP server to Claude Desktop, edit the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file does not exist, you may need to enable it under Settings > Developer in Claude Desktop. Restart Claude Desktop after editing to see the hammer icon in the input box.

The configuration file for Cursor is located at ~/.cursor/mcp.json.

Note: As of version 0.48.0, Cursor supports unauthenticated SSE servers directly. However, if your MCP server uses the official MCP OAuth authorization protocol, you must still use a "command" server configuration that calls mcp-remote.

The client uses Protected Resource Metadata (RFC 9728) to automatically discover the OAuth configuration of the remote MCP server.

When connecting, the client:

1. Probes the MCP server for the WWW-Authenticate header.
2. Fetches the Protected Resource Metadata (PRM).
3. Identifies the authorizationServerUrl and any supported scopes.

If no Protected Resource Metadata is found, the client defaults to using the server's own URL as the authorization server.

MCP Remote uses a hashed file naming convention to isolate configurations for different servers. Files are stored in the configuration directory using the pattern {server_hash}_{filename}.

Commonly used files include:

• {server_hash}_client_info.json: Contains OAuth client registration details.
• {server_hash}_tokens.json: Contains OAuth access and refresh tokens.
• {server_hash}_code_verifier.txt: Contains the PKCE code verifier for the current OAuth flow.
• {server_hash}_lock.json: A lockfile used to manage running server instances.

The NodeOAuthClientProvider determines the effectiveScope used in authorization requests using a specific priority hierarchy. This ensures that the most specific or recently provided scope requirements are honored:

1. staticOAuthClientMetadata.scope: Highest priority; if provided in the constructor options.
2. wwwAuthenticateScope: Scope provided via the WWW-Authenticate header.
3. protectedResourceMetadata.scopes_supported: Scopes defined in the protected resource metadata (RFC 9728).
4. clientInformation.scope: The scope returned during the client registration response.
5. authorizationServerMetadata.scopes_supported: Scopes supported by the authorization server.
6. Fallback: If no other scope is found, it defaults to 'openid email profile'.

The mcp-remote client is a command-line tool designed to connect to an MCP server using SSE (Server-Sent Events) with OAuth authentication.

To run the client, use the following command structure:

npx tsx client.ts <https://server-url> [callback-port] [--debug]

Arguments

• <https://server-url>: The URL of the remote MCP server.
• [callback-port]: (Optional) The port to use for the OAuth callback. If not specified, an available port will be automatically selected.
• --debug: (Optional) Enables debug logging.

npx tsx client.ts https://example.remote/server [callback-port]

If you experience persistent authentication issues, you can clear all locally stored credential information. mcp-remote stores credentials in ~/.mcp-auth by default, or in the directory specified by the MCP_REMOTE_CONFIG_DIR environment variable.

To clear the credentials, run:

rm -rf ~/.mcp-auth

After clearing, restart your MCP client. If you encounter the specific error Authentication Error Token exchange failed: HTTP 400 at the /callback URL, clearing this directory is the recommended fix.

To view MCP logs in real-time for debugging, use the following commands based on your operating system:

MacOS / Linux:

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

WSL (Bash):

tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"

Windows (PowerShell):

Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20