npm package: @greystar/dp-mcp-proxy
Description: Direct MCP proxy with OAuth 2.0 PKCE support for Data Profiler
Author: Greystar Development Team
Latest version: 1.0.1

# DP MCP Proxy

A pure Node.js MCP proxy that implements OAuth 2.0 with PKCE flow to connect to your MCP server. This proxy provides the same functionality as `mcp-remote` but with full control over the authentication flow and better error handling.

## Features

- **OAuth 2.0 with PKCE**: Secure authentication using authorization code flow with PKCE
- **Token caching**: Saves tokens to avoid re-authentication on every startup
- **Token validation**: Tests cached tokens before use
- **Automatic token refresh**: Detects expired tokens and clears cache for re-authentication
- **Session management**: Maintains MCP session IDs across requests
- **Automatic session recovery**: Reinitializes session when server restarts or connection is lost
- **Connection resilience**: Automatically retries on connection errors with intelligent backoff
- **Cross-platform**: Works on Windows, macOS, and Linux
- **Self-signed SSL support**: Can connect to servers with self-signed certificates

## How It Works

### OAuth Flow
1. **Authorization**: Opens browser to MCP server's `/authorize` endpoint
2. **Callback**: Local HTTP server receives authorization code
3. **Token Exchange**: Exchanges code for access token at `/token` endpoint
4. **Token Storage**: Saves token to `~/.dp_mcp_auth/token.json`

### MCP Communication
1. **Stdio Protocol**: Reads JSON-RPC messages from stdin (Claude Desktop)
2. **Notification Filtering**: Skips notifications (messages without `id` field) - they don't require responses
3. **HTTP Requests**: Forwards to MCP server with `Authorization: Bearer <token>` header
4. **Session Tracking**: Maintains session ID in `mcp-session-id` header
5. **Response Forwarding**: Sends server responses back to stdout

### Error Handling & Resilience
- **401 Unauthorized**: Clears token cache and exits for Claude Desktop to restart
- **Token validation failure**: Triggers fresh OAuth flow
- **Session recovery**: Automatically reinitializes session when server restarts
- **Connection retry**: Detects ECONNREFUSED/ECONNRESET and retries with 1 second delay
- **Invalid session handling**: Detects 400/403/410 errors, clears session, and automatically reinitializes
- **Automatic recovery**: Up to 2 retry attempts with session reinitialization
- **Connection errors**: Logged with detailed error messages

## Installation

### Option 1: Use directly with node

```bash
cd oauth-proxy/dp-mcp-proxy
node server.js
```

### Option 2: Make executable

```bash
chmod +x server.js
./server.js
```

## Configuration

Configure Claude Desktop to use this proxy:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "data-profiler": {
      "command": "node",
      "args": [
        "c:\\Important Documents\\code\\gdt-mcp\\oauth-proxy\\dp-mcp-proxy\\server.js"
      ],
      "env": {
        "MCP_SERVER_URL": "https://gsamcp01.greystar.com:7081/mcp",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}
```

## Environment Variables

- `MCP_SERVER_URL` - MCP server URL (default: `https://gsamcp01.greystar.com:7081/mcp`)
- `NODE_TLS_REJECT_UNAUTHORIZED` - Set to `0` to allow self-signed certificates

## File Locations

- **Log file**: `~/.dp-mcp-proxy.log`
- **Token cache**: `~/.dp-mcp-auth/token.json`

## Logging

All activity is logged to `~/.dp-mcp-proxy.log`:

- OAuth flow progress
- Token validation
- Request/response details (method names)
- Errors and warnings
- Session management

## Troubleshooting

### OAuth browser doesn't open

The proxy will print the authorization URL. Manually copy and paste it into your browser:

```
[INFO] Please authorize by visiting: https://...
```

### Token expired errors

The proxy automatically detects expired tokens:
1. Clears token cache
2. Exits cleanly
3. Claude Desktop restarts the connection
4. Fresh OAuth flow triggered

### Connection refused

Check that:
1. MCP server is running
2. `MCP_SERVER_URL` is correct
3. Network/firewall allows connection

### SSL certificate errors

Set environment variable:
```bash
NODE_TLS_REJECT_UNAUTHORIZED=0
```

Or in Claude Desktop config:
```json
"env": {
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
```

## Differences from mcp-remote

| Feature | dp-mcp-proxy | mcp-remote |
|---------|--------------|------------|
| Language | Pure Node.js | Node.js (compiled) |
| OAuth coordination | Single process | Multi-process coordination |
| Token storage | `~/.dp-mcp-auth/` | `~/.mcp-auth/` |
| Session management | Explicit header tracking | Automatic |
| Error handling | Detailed logging | Limited visibility |
| SSL certificates | Configurable | Limited control |
| Wrappable | Yes | No (coordination issues) |

## Advantages

1. **No coordination issues**: Single process, no OAuth coordination complexity
2. **Better error handling**: Detailed logging and error messages
3. **Full control**: Can modify OAuth flow, add custom headers, etc.
4. **Easier debugging**: Pure JavaScript, readable code
5. **Token management**: Explicit control over caching and validation

## Requirements

- Node.js >= 18.0.0
- Network access to MCP server
- Browser for OAuth authentication

## Security Notes

- Tokens are stored in `~/.dp-mcp-auth/` with restrictive permissions
- Uses PKCE (Proof Key for Code Exchange) for secure OAuth flow
- State parameter prevents CSRF attacks
- Local callback server only accepts localhost connections

## License

MIT