MCP Remote with Okta/Adobe IMS Authentication

Un servidor MCP remoto que utiliza Adobe IMS/Okta para la autenticación.

Documentación

MCP Remote con Autenticación de Adobe y Okta

Un envoltorio para mcp-remote que maneja la autenticación de Adobe IMS u Okta utilizando el flujo implícito de OAuth, proporcionando autenticación sin interrupciones para servidores MCP protegidos.

Características

🔐 OAuth Multi-Proveedor: Implementa el flujo implícito de OAuth de Adobe y Okta para una autenticación segura de usuarios.
🔄 Gestión de Tokens: Almacenamiento automático de tokens, validación y manejo de expiración.
🖥️ Multiplataforma: Funciona en macOS, Windows y Linux.
🚀 Cero Mantenimiento: Configúralo una vez, no te preocupes por los tokens nuevamente.
🔧 Configurable: Soporte para múltiples entornos, ámbitos y métodos de autenticación.
🔒 Almacenamiento Seguro: Los tokens se almacenan de forma segura en el directorio de inicio del usuario.
🎯 Listo para Producción: Manejo robusto de errores tanto para Adobe como para Okta.

Instalación

Vía npx (Recomendado)

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

Instalación Global

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

Configuración

Variables de Entorno

Variable	Requerida	Predeterminada	Descripción
`AUTH_PROVIDER`	Opcional	`adobe`	Proveedor de autenticación (`adobe` o `okta`)
`ADOBE_CLIENT_ID`	✅ Si `AUTH_PROVIDER` es `adobe`	-	ID de cliente para Adobe IMS
`ADOBE_SCOPE`	Opcional	`AdobeID,openid`	Ámbito de OAuth para Adobe IMS
`ADOBE_IMS_ENV`	Opcional	`prod`	Entorno de IMS (`prod`, `stage`, `dev`)
`OKTA_CLIENT_ID`	✅ Si `AUTH_PROVIDER` es `okta`	-	ID de cliente para Okta
`OKTA_DOMAIN`	✅ Si `AUTH_PROVIDER` es `okta`	-	Tu dominio de Okta (por ejemplo, `dev-12345.okta.com`)
`OKTA_SCOPE`	Opcional	`openid profile email`	Ámbito de OAuth para Okta
`REDIRECT_URI`	Opcional	`http://localhost:8080/callback`	URI de redirección de OAuth
`AUTH_METHOD`	Opcional	`jwt`	Método de autenticación (`jwt` o `access_token`)
`DEBUG_MODE`	Opcional	`false`	Habilitar modo de depuración para solución de problemas
`AUTO_REFRESH`	Opcional	`true`	Habilitar renovación automática de tokens
`REFRESH_THRESHOLD`	Opcional	`10`	Umbral de renovación automática en minutos

Configuración de MCP

Para 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"
      }
    }
  }
}

Para 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"
      }
    }
  }
}

Uso

Como Servidor MCP (Caso de Uso Principal)

El script detecta automáticamente el proveedor de autenticación configurado y maneja la autenticación del usuario de forma transparente.

Para Adobe:

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

Para 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

Comandos CLI

El paquete también proporciona comandos CLI para la gestión de tokens:

# 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

Cómo Funciona

Este envoltorio implementa el flujo implícito de OAuth para la autenticación:

Configuración de OAuth: Configura los parámetros de OAuth para el proveedor seleccionado (Adobe u Okta).
Autenticación en el Navegador: Abre el navegador para una autenticación segura del usuario.
Captura de Tokens: El servidor HTTP local captura la devolución de llamada de OAuth con los tokens.
Almacenamiento de Tokens: Almacena los tokens de forma segura con seguimiento de expiración.
Intercambio de JWT: Intercambio opcional de tokens JWT para servidores que requieren autenticación JWT.
Inicio de MCP: Inicia mcp-remote con el encabezado Authorization: Bearer <token>.

Flujo de Autenticación

El paquete implementa un flujo completo de OAuth implícito:

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

Entornos

La biblioteca admite múltiples entornos de Adobe IMS. Para Okta, el dominio se configura directamente a través de OKTA_DOMAIN.

Producción (prod) - Entorno de producción predeterminado de Adobe
Stage (stage, stg) - Entorno de staging de Adobe para pruebas
Desarrollo (dev, development) - Entorno de desarrollo de Adobe

export ADOBE_IMS_ENV="stage"  # Use Adobe staging environment

Solución de Problemas

Problemas Comunes

"ID de cliente no encontrado"

# Ensure ADOBE_CLIENT_ID or OKTA_CLIENT_ID is set for your chosen AUTH_PROVIDER

"Autenticación fallida"

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

"Parámetro de estado de OAuth inválido"

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

"Validación de token fallida"

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

"Renovación automática fallida"

# 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

"Error de cliente para el comando: ocurrió un error del sistema (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"
      }
    }
  }
}

Modo de Depuración

Para una solución de problemas detallada, habilita el modo de depuración:

# 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

El modo de depuración muestra:

Resultados de validación de configuración
Tiempos de expiración y validez de tokens
Progreso paso a paso del flujo de OAuth
Programación del temporizador de renovación automática
Detalles de solicitudes de red
Trazas de pila de errores

Diagnóstico Manual

Para depurar problemas de autenticación:

# 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

Arquitectura

Este paquete está construido con:

Flujo Implícito de OAuth - Para aplicaciones del lado del cliente
Soporte Multi-Proveedor - Adobe IMS y Okta
Renovación Automática - Renovación de tokens en segundo plano con temporización configurable
Modo de Depuración - Registro completo para solución de problemas
mcp-remote - Cliente de servidor remoto MCP
Node.js 18+ - Entorno de ejecución de JavaScript moderno
Servidor HTTP Nativo - Para el manejo de devoluciones de llamada de OAuth

La implementación proporciona un manejo robusto de errores, gestión automática de tokens y sigue las mejores prácticas de seguridad de OAuth.

Limpieza de procesos: Los temporizadores se limpian adecuadamente al salir

Renovación Automática

El envoltorio renueva automáticamente los tokens antes de que expiren para garantizar un servicio ininterrumpido:

# 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

Características de renovación automática:

Renovación en segundo plano: Los tokens se renuevan automáticamente antes de la expiración
Umbral configurable: Establece cuántos minutos antes de la expiración se debe activar la renovación
Respaldo elegante: Si la renovación automática falla, se activa la autenticación manual
Limpieza de procesos: Los temporizadores se limpian adecuadamente al salir

Contribuciones

¡Las contribuciones son bienvenidas! Asegúrate de que todas las pruebas pasen y mantén la cobertura de código por encima del 75%.

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

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más información.