MCP Transparent Proxy Server

Servidor MCP (Model Context Protocol) que atua como um proxy transparente entre sistemas OAuth e servidores MCP com autenticação simples. O proxy é invisível para a IA - tools, resources e prompts do servidor externo aparecem como se fossem nativos.

🎯 Objetivo

Este servidor atua como um bridge duplo de autenticação, resolvendo dois problemas de incompatibilidade:

Cliente → Este Servidor: Autenticação OAuth 2.1 com GitHub
Este Servidor → MCP Externo: Autenticação via API (email/senha → Bearer token)

Fluxo Completo:

┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Cliente │ │ MCP Proxy │ │ Servidor MCP │ │ MCP │◄───────►│ (Este projeto) │◄───────►│ Externo │ │ │ OAuth │ │ Bearer │ (API Login) │ │ GitHub │ 2.1 │ OAuth + API │ Token │ Email/Pass │ └─────────────┘ └──────────────────┘ └─────────────────┘

🚀 Características

Autenticação Dupla:

🔐 OAuth 2.1 com GitHub - Cliente autentica via OAuth no frontend
🔑 API Login Automático - Servidor faz login automático na API externa (email/senha)
🎫 Bearer Token Management - Gerencia tokens automaticamente para o servidor MCP externo
🔄 Auto Refresh Token - Renova tokens expirados automaticamente
⏱️ Token Caching - Cache inteligente de tokens com validação de expiração

Proxy Features:

🌉 Bridge Transparente - Conecta diferentes tipos de autenticação
🛠️ Proxy Tools - 6 ferramentas para acessar servidor MCP externo
📡 SSE Transport - Server-Sent Events para comunicação em tempo real
🔄 Auto-Reconnect - Reconexão automática em caso de falha de autenticação
🔒 JWT Security - Proteção de rotas com JWT
💉 Dependency Injection - Sistema DI completo do NestJS
📝 Logs Detalhados - Monitoramento completo de autenticação e proxy
🛡️ Error Recovery - Recuperação automática de erros de token expirado

📦 Instalação

pnpm install

⚙️ Configuração

1. Criar GitHub OAuth App

Acesse: https://github.com/settings/developers
Clique em "New OAuth App"
Preencha:
- Application name: mcp-redirect-server
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/auth/callback
Copie o Client ID e Client Secret

2. Configurar variáveis de ambiente

Crie um arquivo .env baseado no .env.example:

cp .env.example .env

Edite o .env e adicione suas credenciais:

# OAuth Provider (GitHub) - Para autenticação do cliente GITHUB_CLIENT_ID=seu_client_id_aqui GITHUB_CLIENT_SECRET=seu_client_secret_aqui # JWT Configuration (mínimo 32 caracteres) JWT_SECRET=my-super-secure-jwt-secret-key-with-at-least-32-characters # Server Configuration SERVER_URL=http://localhost:3000 RESOURCE_URL=http://localhost:3000/sse # Port PORT=3000 # External API Authentication - Para autenticação no servidor MCP externo EXTERNAL_API_LOGIN_URL=https://api-externa.com/auth/login EXTERNAL_API_USER=seu_email@example.com EXTERNAL_API_PASSWORD=sua_senha_segura # External MCP Server - URL SSE do servidor MCP externo EXTERNAL_MCP_URL=https://api-externa.com/sse

3. Descrição das Variáveis

Autenticação do Cliente (OAuth GitHub):

GITHUB_CLIENT_ID - Client ID do OAuth App do GitHub
GITHUB_CLIENT_SECRET - Client Secret do OAuth App do GitHub
JWT_SECRET - Chave secreta para JWT (mínimo 32 caracteres)

Autenticação no Servidor Externo (API Login):

EXTERNAL_API_LOGIN_URL - URL da API de login do servidor externo
- Exemplo: https://meuservidor.com/auth/login
- O servidor fará POST com { email, password } nesta URL
EXTERNAL_API_USER - Email/usuário para autenticação na API externa
EXTERNAL_API_PASSWORD - Senha para autenticação na API externa

Configuração do Proxy MCP:

EXTERNAL_MCP_URL - URL SSE do servidor MCP externo
- Exemplo: https://meuservidor.com/sse
- Deve ser o endpoint SSE que implementa o protocolo MCP

Importante:

O servidor faz login automático na EXTERNAL_API_LOGIN_URL usando email/senha
A resposta deve conter um campo token ou access_token
Opcionalmente, pode conter expires_in (tempo de expiração em segundos)
Se expires_in não for fornecido, assume-se 1 hora de validade
Este token é usado como Bearer token nas requisições para EXTERNAL_MCP_URL
O token é automaticamente renovado quando próximo da expiração (5 minutos antes)

🏃 Executar o projeto

# desenvolvimento pnpm run start:dev # produção pnpm run start:prod

O servidor estará disponível em: http://localhost:3000

🔌 Endpoints

Endpoints OAuth (Cliente):

GET /.well-known/oauth-authorization-server - Metadata do servidor OAuth (RFC 8414)
GET /.well-known/oauth-protected-resource - Metadata MCP (RFC 9728)
POST /auth/register - Registro dinâmico de cliente (RFC 7591)
GET /auth/authorize - Endpoint de autorização OAuth
GET /auth/callback - Callback OAuth do GitHub
POST /auth/token - Endpoint de token OAuth
POST /auth/revoke - Revogação de token OAuth

Endpoint MCP:

GET /sse - Endpoint SSE para conexão MCP (requer autenticação OAuth)

🧪 Testar com MCP Inspector

Abra o navegador em: http://localhost:3000/mcp
Configure o Inspector:
- Transport Type: SSE
- URL: http://localhost:3000/sse
- Connection Type: Via Proxy
Clique em Authentication para configurar OAuth
Clique em Connect

A Client não sabe que existe um proxy! 🎭

� Como Funciona

Fluxo de Autenticação Dupla:

1. Cliente se autentica no Proxy (OAuth GitHub):

Cliente → GET /auth/authorize → Redireciona para GitHub → Usuário autoriza → GET /auth/callback → Recebe JWT token

2. Proxy se autentica no Servidor Externo (API Login):

Proxy → POST EXTERNAL_API_LOGIN_URL → Body: { email: USER, password: PASS } → Recebe: { token: "Bearer..." } → Armazena token

3. Cliente usa o Proxy com proxy tools:

Cliente → callTool('proxy_list_tools') com JWT Proxy → Valida JWT do cliente Proxy → Conecta ao servidor externo com Bearer token Proxy → client.listTools() via SSE Servidor Externo → Retorna lista de tools Proxy → Retorna resposta ao cliente

Fluxo Completo de uma Chamada:

┌─────────┐ 1. OAuth JWT ┌───────────┐ 2. Bearer Token ┌──────────┐ │ Cliente │ ───────────────→ │ Proxy │ ─────────────────→│ Servidor │ │ MCP │ │ Server │ │ Externo │ │ │ ←─────────────── │ │ ←──────────────── │ MCP │ └─────────┘ 4. Resposta └───────────┘ 3. Resposta └──────────┘

Inicialização Automática:

Quando o servidor inicia:

✅ Configura OAuth com GitHub para clientes
✅ Faz login automático na API externa
✅ Armazena o token com informações de expiração
✅ Conecta ao servidor MCP externo via SSE com Bearer token
✅ Registra as proxy tools
✅ Fica pronto para aceitar conexões de clientes

Sistema de Refresh Token:

O servidor implementa um sistema inteligente de gerenciamento de tokens:

Cache de Token:

┌──────────────────────────────────────────────────────┐ │ Token armazenado em memória com timestamp │ │ Validade: expires_in - 5 minutos (margem segurança) │ │ Reutilizado enquanto válido (evita logins extras) │ └──────────────────────────────────────────────────────┘

Renovação Automática:

1️⃣ Antes de cada operação MCP → Verifica se token está próximo de expirar → Se sim, renova automaticamente 2️⃣ Em caso de erro de autenticação (401/403) → Detecta erro de autenticação → Força refresh do token → Reconecta com novo token → Retenta operação automaticamente

Fluxo de Refresh:

Operação MCP solicitada ↓ Verifica expiração do token ↓ Token válido? ─── NÃO ──→ POST /auth/login │ ↓ SIM Novo token + expires_in ↓ ↓ Usa token em cache Atualiza cache ↓ ↓ └──────────→ Executa operação MCP ↓ Erro 401/403? ─── SIM ──→ Força refresh │ ↓ NÃO Reconecta cliente ↓ ↓ Retorna resultado Retenta operação

Benefícios do Sistema:

✅ Zero Downtime: Tokens renovados antes de expirar
✅ Recuperação Automática: Erros de autenticação tratados automaticamente
✅ Performance: Cache evita logins desnecessários
✅ Transparente: Cliente não percebe renovações
✅ Resiliente: Reconexão automática em falhas

📚 Documentação

Conceitos principais:

Double Authentication Bridge: Ponte entre OAuth (cliente) e API Login (servidor externo)
Proxy Tools: ferramentas para acessar servidor MCP externo de forma controlada
Token Management: Gerenciamento automático de JWT (cliente) e Bearer tokens (servidor)
Auto Refresh Token: Sistema inteligente que renova tokens antes de expirar
Token Caching: Cache de tokens com validação de expiração para melhor performance
Error Recovery: Recuperação automática de erros de autenticação com retry
SSE Transport: Comunicação em tempo real via Server-Sent Events

Links úteis:

🚀 Benefícios

✅ Bridge Duplo: Conecta OAuth (cliente) com API Login (servidor externo)
✅ Sem Modificação: Usa servidores MCP existentes sem mudanças
✅ Segurança em Camadas: OAuth no frontend + Bearer token no backend
✅ Gerenciamento Automático: Tokens gerenciados e renovados automaticamente
✅ Zero Downtime: Renovação preventiva de tokens antes da expiração
✅ Resiliente: Recuperação automática de falhas de autenticação
✅ Performance Otimizada: Cache de tokens evita logins desnecessários
✅ Isolamento de Credenciais: Servidor externo nunca vê credenciais OAuth
✅ Logs Detalhados: Monitoramento completo de autenticação e proxy
✅ Produção-Ready: Implementação completa do protocolo MCP
✅ Flexível: Fácil configuração via variáveis de ambiente

🔒 Segurança

✅ OAuth 2.1: Autenticação segura de clientes via GitHub
✅ JWT Tokens: Tokens assinados e validados
✅ Credenciais Isoladas: Senhas apenas em variáveis de ambiente
✅ Logs Sanitizados: Senhas nunca aparecem nos logs
✅ Bearer Tokens: Comunicação segura com servidor externo
✅ Token Rotation: Renovação automática de tokens para segurança contínua
✅ Margem de Segurança: Tokens renovados 5 minutos antes de expirar
✅ HTTPS Ready: Preparado para produção com HTTPS

🎯 Formato de Resposta da API Externa

A API externa (EXTERNAL_API_LOGIN_URL) deve retornar uma resposta JSON no seguinte formato:

Resposta Mínima:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Resposta Recomendada (com expiração):

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600 }

Campos suportados:

token ou access_token (string, obrigatório) - Bearer token para autenticação
expires_in (number, opcional) - Tempo de expiração em segundos (padrão: 3600)

Comportamento:

Se expires_in for fornecido, o servidor usa esse valor
Caso contrário, assume 1 hora (3600 segundos) de validade
Token é renovado automaticamente 5 minutos antes de expirar

🛠️ Troubleshooting

Erro: "Authentication configuration is incomplete"

Verifique se todas as variáveis estão no .env:

EXTERNAL_API_LOGIN_URL
EXTERNAL_API_USER
EXTERNAL_API_PASSWORD

Erro: "Failed to authenticate"

Confirme que a URL de login está correta
Verifique se email/senha são válidos
Confirme que a API retorna token ou access_token

Erro: "EXTERNAL_MCP_URL not configured"

Configure EXTERNAL_MCP_URL no .env com a URL SSE do servidor externo.

Cliente não consegue conectar via OAuth

Verifique GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET
Confirme que a callback URL no GitHub está correta: http://localhost:3000/auth/callback
Verifique se JWT_SECRET tem pelo menos 32 caracteres

Token expira muito rápido

Verifique se a API externa retorna expires_in correto
O servidor renova tokens 5 minutos antes de expirar
Confira os logs para ver quando tokens estão sendo renovados
Logs de exemplo:
[McpProxyService] Refreshing authentication token... [McpProxyService] Token refreshed successfully. Expires in 3600s [McpProxyService] Using cached token

Erro: "MCP client is not connected"

O servidor tenta reconectar automaticamente
Verifique se EXTERNAL_MCP_URL está acessível
Confira logs de erro de conexão
Sistema tentará reconectar na próxima operação

Erro 401/403 do servidor externo

Sistema detecta automaticamente e força refresh do token
Se persistir, verifique credenciais EXTERNAL_API_USER e EXTERNAL_API_PASSWORD
Confirme que a API de login está funcionando corretamente

📝 Licença

MIT licensed