mcp-remote-with-okta

MCP Remote with Adobe and Okta Authentication

A wrapper for mcp-remote that handles Adobe IMS or Okta authentication using OAuth implicit flow, providing seamless authentication for protected MCP servers.

Features

• 🔐 Multi-Provider OAuth: Implements Adobe's and Okta's OAuth implicit flow for secure user authentication.
• 🔄 Token Management: Automatic token storage, validation, and expiration handling.
• 🖥️ Cross-Platform: Works on macOS, Windows, and Linux.
• 🚀 Zero Maintenance: Set it once, never worry about tokens again.
• 🔧 Configurable: Support for multiple environments, scopes, and authentication methods.
• 🔒 Secure Storage: Tokens stored securely in user's home directory.
• 🎯 Production Ready: Robust error handling for both Adobe and Okta.

Installation

Via npx (Recommended)

npx mcp-remote-with-okta <mcp-url>

Global Installation

npm install -g mcp-remote-with-okta
mcp-remote-with-okta <mcp-url>

Configuration

Environment Variables

Variable	Required	Default	Description
AUTH_PROVIDER	Optional	adobe	Authentication provider (adobe or okta)
ADOBE_CLIENT_ID	✅ If AUTH_PROVIDER is adobe	-	Client ID for Adobe IMS
ADOBE_SCOPE	Optional	AdobeID,openid	OAuth scope for Adobe IMS
ADOBE_IMS_ENV	Optional	prod	IMS environment (prod, stage, dev)
OKTA_CLIENT_ID	✅ If AUTH_PROVIDER is okta	-	Client ID for Okta
OKTA_DOMAIN	✅ If AUTH_PROVIDER is okta	-	Your Okta domain (e.g., dev-12345.okta.com)
OKTA_SCOPE	Optional	openid profile email	OAuth scope for Okta
REDIRECT_URI	Optional	http://localhost:8080/callback	OAuth redirect URI
AUTH_METHOD	Optional	jwt	Authentication method (jwt or access_token)
DEBUG_MODE	Optional	false	Enable debug mode for troubleshooting
AUTO_REFRESH	Optional	true	Enable automatic token refresh
REFRESH_THRESHOLD	Optional	10	Auto-refresh threshold in minutes

MCP Configuration

For Adobe

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote-with-okta",
        "https://your-mcp-server.com/mcp"
      ],
      "env": {
        "AUTH_PROVIDER": "adobe",
        "ADOBE_CLIENT_ID": "your_client_id_here",
        "ADOBE_IMS_ENV": "prod"
      }
    }
  }
}

For Okta

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote-with-okta",
        "https://your-mcp-server.com/mcp"
      ],
      "env": {
        "AUTH_PROVIDER": "okta",
        "OKTA_CLIENT_ID": "your_okta_client_id",
        "OKTA_DOMAIN": "your_okta_domain.okta.com"
      }
    }
  }
}

Usage

As MCP Server (Primary Use Case)

The script automatically detects the configured authentication provider and handles user authentication transparently.

For Adobe:

export AUTH_PROVIDER=adobe
export ADOBE_CLIENT_ID=your_client_id
npx mcp-remote-with-okta https://my.mcp-server.com/mcp

For Okta:

export AUTH_PROVIDER=okta
export OKTA_CLIENT_ID=your_client_id
export OKTA_DOMAIN=your.okta.domain
npx mcp-remote-with-okta https://my.mcp-server.com/mcp

CLI Commands

The package also provides CLI commands for token management:

# Authenticate user and get token
npx mcp-remote-with-okta <mcp-url> authenticate

# Check token status
npx mcp-remote-with-okta <mcp-url> status

# Display current token
npx mcp-remote-with-okta <mcp-url> token

# Clear stored tokens
npx mcp-remote-with-okta <mcp-url> clear

# Show help
npx mcp-remote-with-okta <mcp-url> help

How It Works

This wrapper implements the OAuth implicit flow for authentication:

• OAuth Setup: Configures OAuth parameters for the selected provider (Adobe or Okta).
• Browser Authentication: Opens browser for secure user authentication.
• Token Capture: Local HTTP server captures OAuth callback with tokens.
• Token Storage: Securely stores tokens with expiration tracking.
• JWT Exchange: Optional JWT token exchange for servers requiring JWT authentication.
• MCP Launch: Launches mcp-remote with Authorization: Bearer <token> header.

Authentication Flow

The package implements a complete OAuth implicit flow:

1. Generate OAuth URL → Auth Server (Adobe IMS or Okta)
2. Open Browser → User Authentication
3. Capture Callback → Local HTTP Server  
4. Extract Tokens → From URL Fragment
5. Store Tokens → Secure Local Storage
6. Launch MCP → With Auth Header

Environments

The library supports multiple Adobe IMS environments. For Okta, the domain is configured directly via OKTA_DOMAIN.

• Production (prod) - Default Adobe production environment
• Stage (stage, stg) - Adobe staging environment for testing
• Development (dev, development) - Adobe development environment

export ADOBE_IMS_ENV="stage"  # Use Adobe staging environment

Troubleshooting

Common Issues

"Client ID not found"

# Ensure ADOBE_CLIENT_ID or OKTA_CLIENT_ID is set for your chosen AUTH_PROVIDER

"Authentication failed"

# Check that your Developer Console project (Adobe or Okta) is properly configured
# Verify the client ID is correct for the target environment

"OAuth state parameter invalid"

# This usually indicates a callback security issue
# Clear tokens and try again
npx mcp-remote-with-okta <url> clear

"Token validation failed"

# Clear stored tokens and re-authenticate
npx mcp-remote-with-okta <url> clear
npx mcp-remote-with-okta <url> authenticate

"Auto-refresh failed"

# Check debug logs to see the specific error
export DEBUG_MODE=true
npx mcp-remote-with-okta <url> status

# Disable auto-refresh if causing issues
export AUTO_REFRESH=false

"Client error for command A system error occurred (spawn npx ENOENT)"

# If you encounter this error when using npx in MCP configuration,
# this often happens when the Node.js/npm environment isn't properly 
set up

# Solution: Create an npx wrapper script
cat > ~/.cursor/npx-wrapper.sh << 'SCRIPT'
#!/bin/bash

# Source nvm to get the correct node version
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Use your preferred node version (adjust as needed)
nvm use 22.0.0 >/dev/null 2>&1

# Execute npx with all passed arguments
exec npx "$@"
SCRIPT

# Make the script executable
chmod +x ~/.cursor/npx-wrapper.sh

# Update your ~/.cursor/mcp.json to use the wrapper instead of npx:
{
  "mcpServers": {
    "your-server": {
      "command": "/Users/your-username/.cursor/npx-wrapper.sh",
      "args": [
        "mcp-remote-with-okta",
        "https://your-mcp-server.com/mcp"
      ],
      "env": {
        "AUTH_PROVIDER": "adobe",
        "ADOBE_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Debug Mode

For detailed troubleshooting, enable debug mode:

# Enable debug logging for the selected provider
export DEBUG_MODE=true
export AUTH_PROVIDER=okta # or 'adobe'
npx mcp-remote-with-okta <url> status

# Or use standard DEBUG variable
export DEBUG=okta # or 'adobe'
npx mcp-remote-with-okta <url> authenticate

Debug mode shows:

• Configuration validation results
• Token expiration times and validity
• OAuth flow step-by-step progress
• Auto-refresh timer scheduling
• Network request details
• Error stack traces

Manual Diagnostics

For debugging authentication issues:

# Check authentication status with debug info
export DEBUG_MODE=true
npx mcp-remote-with-okta <url> status

# View current token details
npx mcp-remote-with-okta <url> token

# Test authentication flow with full logging
export DEBUG_MODE=true
npx mcp-remote-with-okta <url> authenticate

# Clear tokens and start fresh
npx mcp-remote-with-okta <url> clear

Architecture

This package is built with:

• OAuth Implicit Flow - For client-side applications
• Multi-Provider Support - Adobe IMS and Okta
• Auto-refresh - Background token refresh with configurable timing
• Debug Mode - Comprehensive logging for troubleshooting
• mcp-remote - MCP remote server client
• Node.js 18+ - Modern JavaScript runtime
• Native HTTP Server - For OAuth callback handling

The implementation provides robust error handling, automatic token management, and follows OAuth security best practices.

• Process cleanup: Timers are properly cleaned up on exit

Auto-Refresh

The wrapper automatically refreshes tokens before they expire to ensure uninterrupted service:

# Enable auto-refresh (default: true)
export AUTO_REFRESH=true

# Set refresh threshold to 5 minutes before expiration
export REFRESH_THRESHOLD=5

# Disable auto-refresh
export AUTO_REFRESH=false

Auto-refresh features:

• Background refresh: Tokens are refreshed automatically before expiration
• Configurable threshold: Set how many minutes before expiration to trigger refresh
• Graceful fallback: If auto-refresh fails, manual authentication is triggered
• Process cleanup: Timers are properly cleaned up on exit

Contributing

Contributions are welcomed! Please ensure all tests pass and maintain code coverage above 75%.

npm test              # Run tests
npm run test:coverage # Run tests with coverage
npm run lint          # Check code style

License

This project is licensed under the MIT License. See LICENSE for more information.