# `mcp-remote-static`
> **This is a fork of [mcp-remote](https://github.com/geelen/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)
```json
{
"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:**
```json
{
"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`:
```json
{
"client_id": "your-client-id",
"client_secret": "your-client-secret"
}
```
Reference in config:
```json
{
"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
```json
{
"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:**
```sh
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:**
```sh
npx mcp-remote-client-static https://server/sse --static-oauth-client-info "{\"client_id\":\"xxx\",\"client_secret\":\"yyy\"}"
```
**Node version:** Requires Node 18+
