# `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+