mcp-remote-static

This is a fork of 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:

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)

With Environment Variables:

Method 2: JSON File

Create oauth_client_info.json:

Reference in config:

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

Troubleshooting

Clear credentials:

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:

Node version: Requires Node 18+