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.