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

cd oauth-proxy/dp-mcp-proxy
node server.js

Option 2: Make executable

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

{
  "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:

NODE_TLS_REJECT_UNAUTHORIZED=0

Or in Claude Desktop config:

"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