MCP Remote with Okta/Adobe IMS Authentication

Um servidor MCP remoto que utiliza Adobe IMS/Okta para autenticação.

Documentação

MCP Remote com Autenticação Adobe e Okta

Um wrapper para mcp-remote que lida com autenticação Adobe IMS ou Okta usando fluxo implícito OAuth, fornecendo autenticação perfeita para servidores MCP protegidos.

Recursos

🔐 OAuth Multi-Provedor: Implementa o fluxo implícito OAuth da Adobe e Okta para autenticação segura de usuários.
🔄 Gerenciamento de Tokens: Armazenamento automático de tokens, validação e tratamento de expiração.
🖥️ Multiplataforma: Funciona em macOS, Windows e Linux.
🚀 Zero Manutenção: Configure uma vez, nunca mais se preocupe com tokens.
🔧 Configurável: Suporte para múltiplos ambientes, escopos e métodos de autenticação.
🔒 Armazenamento Seguro: Tokens armazenados com segurança no diretório inicial do usuário.
🎯 Pronto para Produção: Tratamento robusto de erros para Adobe e Okta.

Instalação

Via npx (Recomendado)

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

Instalação Global

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

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`AUTH_PROVIDER`	Opcional	`adobe`	Provedor de autenticação (`adobe` ou `okta`)
`ADOBE_CLIENT_ID`	✅ Se `AUTH_PROVIDER` for `adobe`	-	ID do Cliente para Adobe IMS
`ADOBE_SCOPE`	Opcional	`AdobeID,openid`	Escopo OAuth para Adobe IMS
`ADOBE_IMS_ENV`	Opcional	`prod`	Ambiente IMS (`prod`, `stage`, `dev`)
`OKTA_CLIENT_ID`	✅ Se `AUTH_PROVIDER` for `okta`	-	ID do Cliente para Okta
`OKTA_DOMAIN`	✅ Se `AUTH_PROVIDER` for `okta`	-	Seu domínio Okta (ex.: `dev-12345.okta.com`)
`OKTA_SCOPE`	Opcional	`openid profile email`	Escopo OAuth para Okta
`REDIRECT_URI`	Opcional	`http://localhost:8080/callback`	URI de redirecionamento OAuth
`AUTH_METHOD`	Opcional	`jwt`	Método de autenticação (`jwt` ou `access_token`)
`DEBUG_MODE`	Opcional	`false`	Ativar modo de depuração para solução de problemas
`AUTO_REFRESH`	Opcional	`true`	Ativar renovação automática de tokens
`REFRESH_THRESHOLD`	Opcional	`10`	Limite de renovação automática em minutos

Configuração 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)

O script detecta automaticamente o provedor de autenticação configurado e lida com a autenticação do usuário 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

O pacote também fornece comandos CLI para gerenciamento 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

Como Funciona

Este wrapper implementa o fluxo implícito OAuth para autenticação:

Configuração OAuth: Configura parâmetros OAuth para o provedor selecionado (Adobe ou Okta).
Autenticação no Navegador: Abre o navegador para autenticação segura do usuário.
Captura de Token: Servidor HTTP local captura o callback OAuth com tokens.
Armazenamento de Token: Armazena tokens com segurança com rastreamento de expiração.
Troca JWT: Troca opcional de token JWT para servidores que exigem autenticação JWT.
Inicialização MCP: Inicia mcp-remote com cabeçalho Authorization: Bearer <token>.

Fluxo de Autenticação

O pacote implementa um fluxo implícito OAuth completo:

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

Ambientes

A biblioteca suporta múltiplos ambientes Adobe IMS. Para Okta, o domínio é configurado diretamente via OKTA_DOMAIN.

Produção (prod) - Ambiente de produção padrão da Adobe
Stage (stage, stg) - Ambiente de staging da Adobe para testes
Desenvolvimento (dev, development) - Ambiente de desenvolvimento da Adobe

export ADOBE_IMS_ENV="stage"  # Use Adobe staging environment

Solução de Problemas

Problemas Comuns

"ID do Cliente não encontrado"

# Ensure ADOBE_CLIENT_ID or OKTA_CLIENT_ID is set for your chosen AUTH_PROVIDER

"Falha na autenticação"

# 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 OAuth inválido"

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

"Falha na validação do token"

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

"Falha na renovação automática"

# 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

"Erro do cliente para o comando: ocorreu um erro de 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 Depuração

Para solução de problemas detalhada, ative o modo de depuração:

# 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

O modo de depuração mostra:

Resultados da validação de configuração
Tempos de expiração e validade dos tokens
Progresso passo a passo do fluxo OAuth
Agendamento do temporizador de renovação automática
Detalhes de requisições de rede
Rastreamentos de pilha de erros

Diagnóstico Manual

Para depurar problemas de autenticação:

# 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

Arquitetura

Este pacote é construído com:

Fluxo Implícito OAuth - Para aplicações do lado do cliente
Suporte Multi-Provedor - Adobe IMS e Okta
Renovação Automática - Renovação de tokens em segundo plano com temporização configurável
Modo de Depuração - Registro abrangente para solução de problemas
mcp-remote - Cliente de servidor remoto MCP
Node.js 18+ - Runtime JavaScript moderno
Servidor HTTP Nativo - Para tratamento de callback OAuth

A implementação fornece tratamento robusto de erros, gerenciamento automático de tokens e segue as melhores práticas de segurança OAuth.

Limpeza de processos: Temporizadores são devidamente limpos na saída

Renovação Automática

O wrapper renova automaticamente os tokens antes que expirem para garantir serviço ininterrupto:

# 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

Recursos de renovação automática:

Renovação em segundo plano: Tokens são renovados automaticamente antes da expiração
Limite configurável: Defina quantos minutos antes da expiração para acionar a renovação
Fallback gracioso: Se a renovação automática falhar, a autenticação manual é acionada
Limpeza de processos: Temporizadores são devidamente limpos na saída

Contribuindo

Contribuições são bem-vindas! Por favor, garanta que todos os testes passem e mantenha a cobertura de código acima de 75%.

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

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para mais informações.