mcp-remote-static

This is a fork of mcp-remote with added support for static OAuth client configuration. This package is designed for marketplace scenarios and OAuth servers that require pre-registered clients with static client_id and client_secret, using standard OAuth 2.0 authorization code flow.

Connect MCP clients (Claude Desktop, Cursor, Windsurf) to remote MCP servers with static OAuth client authentication.

⚠️ Marketplace Setup Required: Configure callback URL http://localhost:17091/oauth/callback in your marketplace before use.

Marketplace Configuration

Required: Register callback URL in your marketplace OAuth client settings:

http://localhost:17091/oauth/callback

Configuration:

1. Log in to marketplace admin panel
2. Navigate to OAuth client settings
3. Add http://localhost:17091/oauth/callback to allowed redirect URIs
4. Save configuration

Custom host/port: Update callback URL accordingly (e.g., http://127.0.0.1:17091/oauth/callback for --host 127.0.0.1)

Configuration

Method 1: JSON String (Recommended)

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "mcp-remote-static",
        "https://remote.mcp.server/sse",
        "--static-oauth-client-info",
        "{\"client_id\":\"your-client-id\",\"client_secret\":\"your-client-secret\"}"
      ]
    }
  }
}

With Environment Variables:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "mcp-remote-static",
        "https://remote.mcp.server/sse",
        "--static-oauth-client-info",
        "{\"client_id\":\"${MCP_CLIENT_ID}\",\"client_secret\":\"${MCP_CLIENT_SECRET}\"}"
      ],
      "env": {
        "MCP_CLIENT_ID": "your-client-id",
        "MCP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Method 2: JSON File

Create oauth_client_info.json:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Reference in config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "mcp-remote-static",
        "https://remote.mcp.server/sse",
        "--static-oauth-client-info",
        "@/path/to/oauth_client_info.json"
      ]
    }
  }
}

Client Setup

Configuration Files:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Restart the client after configuration changes.

Configuration Options

Required Arguments

serverUrl (args[0], required)

• MCP server URL
• Example: https://remote.mcp.server/sse

--static-oauth-client-info <value> (required)

• Static OAuth client information
• Format: JSON string or @file-path
• Examples:
  • JSON string: "{\"client_id\":\"xxx\",\"client_secret\":\"yyy\"}"
  • File path: @/path/to/oauth_client_info.json

Optional Arguments

callbackPort (args[1], optional)

• Callback server port number
• Default: 17091 (fixed for static OAuth)
• Example: 17091 or 9696

--debug

• Enable debug logging
• Logs written to: ~/.mcp-auth/{server_hash}_debug.log

--transport <strategy>

• Transport strategy
• Values: sse-only | http-only | sse-first | http-first
• Default: http-first

--ignore-tool <tool-name> (can be used multiple times)

• Ignore specified tools
• Example: --ignore-tool tool1 --ignore-tool tool2

--auth-timeout <seconds>

• OAuth callback timeout in seconds
• Default: 30
• Example: --auth-timeout 60

--header <header-value> (can be used multiple times)

• Custom HTTP request headers
• Format: "HeaderName: value"
• Example: --header "Authorization: Bearer token"

--host <hostname>

• Callback server hostname
• Default: localhost
• Example: --host 127.0.0.1

Complete Example

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "mcp-remote-static",
        "https://remote.mcp.server/sse",
        "17091",
        "--static-oauth-client-info",
        "{\"client_id\":\"your-client-id\",\"client_secret\":\"your-client-secret\"}",
        "--transport",
        "sse-only",
        "--ignore-tool",
        "tool1",
        "--ignore-tool",
        "tool2",
        "--auth-timeout",
        "60",
        "--header",
        "X-Custom-Header: value",
        "--debug"
      ]
    }
  }
}

Troubleshooting

Clear credentials:

rm -rf ~/.mcp-auth

Authentication errors:

• Verify client_id and client_secret are correct
• Verify callback URL matches marketplace: http://localhost:17091/oauth/callback
• Clear credentials and retry

Check logs:

• Claude Desktop: tail -F ~/Library/Logs/Claude/mcp*.log (macOS/Linux)
• Use --debug flag for detailed logs: ~/.mcp-auth/{server_hash}_debug.log

Test connection:

npx mcp-remote-client-static https://server/sse --static-oauth-client-info "{\"client_id\":\"xxx\",\"client_secret\":\"yyy\"}"

Node version: Requires Node 18+