Remote MCP Proxy

Un proxy basado en Docker para acceder a servidores MCP locales a través de la interfaz web de Claude usando el protocolo Remote MCP.

GitHub

Prueba este MCPPatrocinado

Documentación

Proxy MCP Remoto

Utiliza sin problemas tus servidores MCP favoritos en cualquier lugar. Este proyecto empaqueta un pequeño proxy en Go que te permite conectar servidores MCP locales o experimentales a Claude.ai y a la aplicación móvil. Incluso si un servidor aún no es oficialmente "remoto", este proxy lo expone a través del nuevo protocolo MCP Remoto de Claude para que puedas empezar a integrarlo de inmediato.

Por Qué Existe Esto

Los servidores MCP existentes a menudo solo se ejecutan en tu escritorio, lo que hace imposible usarlos con la interfaz web de Claude o con la aplicación móvil. El protocolo MCP Remoto resuelve esto, pero no todos los servidores lo soportan todavía. Este proxy llena ese vacío para que puedas experimentar de inmediato.

Cómo Funciona

Ejecuta el proxy en Docker y este:

Inicia y monitorea tus servidores MCP locales automáticamente
Convierte el tráfico entre HTTP/SSE y MCP JSON-RPC estándar
Aloja varios servidores MCP a la vez bajo diferentes rutas de URL
Reutiliza el formato familiar claude_desktop_config.json
Se apaga limpiamente y limpia cualquier proceso generado
Expone un endpoint /health para que puedas comprobar el estado de un vistazo

🚀 Sistema de Configuración Dinámica

Este proxy ahora cuenta con generación automática de enrutamiento de subdominios a partir de tu archivo config.json. Simplemente define tus servidores MCP en JSON y el sistema crea automáticamente las reglas de enrutamiento de Traefik para cada servidor.

⚡ Inicio Rápido Súper

# 1. Define servers
echo '{"mcpServers":{"memory":{"command":"npx","args":["-y","@modelcontextprotocol/server-memory"]}}}' > config.json

# 2. Set domain  
echo "DOMAIN=yourdomain.com" > .env

# 3. Deploy
make install-deps && make up

# 4. Use in Claude.ai
# → https://memory.mcp.yourdomain.com/sse

Características Clave

✅ Enrutamiento Dinámico de Subdominios: Cada servidor obtiene {server}.mcp.{domain}/sse
✅ Integración Automática con Traefik: Las rutas se generan automáticamente
✅ Escalado Fácil: Agrega servidores editando solo JSON
✅ Listo para Producción: SSL adecuado, balanceo de carga, descubrimiento de servicios

Inicio Rápido

1. Crear Archivo de Configuración

Crea un archivo config.json que describa tus servidores MCP (mismo formato que claude_desktop_config.json):

{
  "mcpServers": {
    "notion-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-notion"],
      "env": {
        "NOTION_TOKEN": "your_notion_token_here"
      }
    },
    "memory-mcp": {
      "command": "python",
      "args": ["-m", "memory_mcp"],
      "env": {}
    }
  }
}

2. Desplegar con Configuración Dinámica

Opción A: Flujo de Trabajo Automatizado con Make (Recomendado)

# Install dependencies (first time only)
make install-deps

# Set your domain
echo "DOMAIN=yourdomain.com" > .env

# Generate configuration and deploy
make up

# View logs
make logs

Opción B: Despliegue Manual con Docker

# Build the image
docker build -t remote-mcp-proxy .

# Run the proxy
docker run -d \
  --name mcp-proxy \
  -p 8080:8080 \
  -v $(pwd)/config.json:/app/config.json:ro \
  remote-mcp-proxy

3. Configurar Variables de Entorno

La configuración de compose espera /home/pezzos/docker/config/secrets/remote_mcp_proxy.env. El archivo está enlazado simbólicamente en este directorio como .env.

cd /home/pezzos/docker/config
cp secrets/remote_mcp_proxy.env secrets/remote_mcp_proxy.env.example  # optional backup
${EDITOR:-nano} secrets/remote_mcp_proxy.env

Contenido de ejemplo:

DOMAIN=proxy.example.com
LOG_LEVEL_SYSTEM=INFO
LOG_LEVEL_MCP=DEBUG
LOG_RETENTION_SYSTEM=24h
LOG_RETENTION_MCP=12h

4. Usar Docker Compose con Traefik

docker-compose up -d

Esto desplegará el servicio con integración de proxy inverso Traefik, haciéndolo accesible en mcp.{DOMAIN} con HTTPS automático.

5. Configurar DNS Wildcard (Requerido)

Configura DNS wildcard para el enrutamiento dinámico de subdominios:

Ejemplo de Configuración DNS (Cloudflare):

Type: A
Name: *.mcp
Content: YOUR_SERVER_IP
Proxy status: Proxied (orange cloud)

Para otros proveedores de DNS, crea un registro A:

*.mcp.your-domain.com    A    YOUR_SERVER_IP

6. Configurar Claude.ai

Abre Claude.ai (requiere plan Pro, Max, Teams o Enterprise) y agrega tus URLs de proxy generadas automáticamente en Configuración > Integraciones:

URLs Generadas Automáticamente (basadas en tu config.json):

https://notion-mcp.mcp.your-domain.com/sse
https://memory-mcp.mcp.your-domain.com/sse
https://sequential-thinking.mcp.your-domain.com/sse

✅ Estado de Integración con Claude.ai: ¡El botón Conectar ahora funciona de manera confiable! El proxy soporta completamente la integración con Claude.ai Remote MCP con gestión de sesiones y descubrimiento de herramientas adecuados.

🔄 Agregar Nuevos Servidores MCP

1. Editar config.json:

{
  "mcpServers": {
    "existing-server": {...},
    "new-server": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

2. Redesplegar:

make restart

3. Usar inmediatamente:

Nueva URL: https://new-server.mcp.your-domain.com/sse
SSL, enrutamiento y balanceo de carga configurados automáticamente

Endpoints de Depuración: Usa estos endpoints para verificar que tus servidores MCP funcionan:

Comprobar estado del servidor: https://mcp.your-domain.com/listmcp
Verificar herramientas disponibles: https://mcp.your-domain.com/listtools/your-server-name

🌐 Estructura de URL Dinámica

Formato Generado Automáticamente: Cada servidor MCP está disponible automáticamente en:

https://{server-name}.mcp.{DOMAIN}/sse

Ejemplos (de tu config.json):

https://memory.mcp.your-domain.com/sse
https://sequential-thinking.mcp.your-domain.com/sse
https://notion.mcp.your-domain.com/sse

Donde {DOMAIN} se establece en tu archivo .env y {server-name} coincide con la clave en tu archivo config.json.

🔧 Referencia de Comandos Make

Comando	Descripción
`make help`	Mostrar todos los comandos disponibles
`make install-deps`	Instalar dependencia gomplate
`make generate`	Generar docker-compose.yml a partir de config.json
`make build`	Construir imágenes Docker
`make up`	Generar configuración e iniciar servicios
`make down`	Detener y eliminar servicios
`make restart`	Reiniciar servicios con nueva configuración
`make logs`	Mostrar registros de servicios
`make clean`	Eliminar archivos generados

¿Por Qué Generación Dinámica de Subdominios?

Claude.ai espera endpoints MCP Remotos a nivel de raíz (/sse), no enrutamiento basado en rutas. Este enfoque automatizado de subdominios:

✅ Coincide con el formato estándar MCP Remoto
✅ Se escala automáticamente con los cambios en config.json
✅ Proporciona separación limpia entre servidores
✅ Elimina la configuración manual de Traefik
✅ Permite el despliegue instantáneo de nuevos servidores

Configuración

El proxy usa el mismo formato de configuración que el claude_desktop_config.json de Claude Desktop:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Variables de Entorno

Variables de Entorno de Docker Compose

Las siguientes variables de entorno son utilizadas por la configuración de Docker Compose:

DOMAIN: Tu nombre de dominio base (por ejemplo, example.com). Los servidores MCP serán accesibles en {server}.mcp.{DOMAIN}

Variables de Entorno del Servidor MCP

Establece variables de entorno para tus servidores MCP en la sección env de config.json
Almacena secretos de forma segura y haz referencia a ellos en tu despliegue Docker
El proxy pasará estas variables de entorno a los procesos MCP que inicie

Docker Compose con Traefik

Configuración de Subdominio Wildcard

El servicio está configurado para funcionar con el proxy inverso Traefik para HTTPS automático y enrutamiento de subdominio wildcard:

version: '3.8'
services:
  remote-mcp-proxy:
    build: .
    container_name: remote-mcp-proxy
    restart: unless-stopped
    volumes:
      - ./config.json:/app/config.json:ro
    environment:
      - GO_ENV=production
    networks:
      - proxy
    labels:
      # Wildcard subdomain routing for dynamic MCP servers
      - traefik.enable=true
      - traefik.http.routers.mcp-wildcard.rule=Host(`*.mcp.${DOMAIN}`)
      - traefik.http.routers.mcp-wildcard.entrypoints=websecure
      - traefik.http.routers.mcp-wildcard.tls=true
      - traefik.http.routers.mcp-wildcard.tls.certresolver=letsencrypt
      - traefik.http.services.mcp-wildcard.loadbalancer.server.port=8080
      
      # Utility endpoints on main domain
      - traefik.http.routers.mcp-main.rule=Host(`mcp.${DOMAIN}`)
      - traefik.http.routers.mcp-main.entrypoints=websecure
      - traefik.http.routers.mcp-main.tls=true
      - traefik.http.routers.mcp-main.tls.certresolver=letsencrypt
      - traefik.http.services.mcp-main.loadbalancer.server.port=8080

networks:
  proxy:
    external: true

Puntos Clave de Configuración:

Regla Wildcard: Host(\*.mcp.${DOMAIN}) captura todos los subdominios como memory.mcp.domain.com
SSL Dinámico: Traefik genera automáticamente certificados SSL para nuevos subdominios
Dominio Principal: mcp.${DOMAIN} para endpoints de utilidad (/health, /listmcp)
Requisito DNS: El registro DNS wildcard *.mcp.domain.com debe estar configurado

Guía de Configuración Completa

Requisitos Previos

Docker y Docker Compose instalados
Nombre de dominio con control de DNS
Proxy inverso Traefik en ejecución (o disposición a configurarlo)

Configuración Paso a Paso

1. Clonar y Configurar

# Clone the repository
git clone <repository-url>
cd remote-mcp-proxy

# Create environment configuration
echo "DOMAIN=your-domain.com" > .env

2. Configurar Tus Servidores MCP

Edita config.json con tus servidores MCP deseados:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "sequential-thinking": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-notion"],
      "env": {
        "NOTION_TOKEN": "your_notion_token_here"
      }
    }
  }
}

3. Configurar DNS (Paso Crítico)

Para Cloudflare:

Ve a la configuración de DNS de tu dominio
Agrega un nuevo registro:
- Tipo: A
- Nombre: *.mcp
- Contenido: La dirección IP de tu servidor
- Estado del proxy: Proxied (nube naranja)

Para otros proveedores de DNS: Crea un registro A wildcard: *.mcp.your-domain.com → YOUR_SERVER_IP

4. Configurar Traefik (Si aún no está en ejecución)

Crea traefik/docker-compose.yml:

version: '3.8'
services:
  traefik:
    image: traefik:v3.0
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    networks:
      - proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/traefik.yml:ro
      - ./acme.json:/acme.json
    environment:
      - CF_API_EMAIL=your-email@example.com  # If using Cloudflare
      - CF_API_KEY=your-cloudflare-api-key   # If using Cloudflare

networks:
  proxy:
    external: true

Crea traefik/traefik.yml:

global:
  checkNewVersion: false

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false

certificatesResolvers:
  letsencrypt:
    acme:
      email: your-email@example.com
      storage: acme.json
      dnsChallenge:  # Recommended for wildcard certificates
        provider: cloudflare
        delayBeforeCheck: 0

5. Desplegar el Proxy MCP

# Create proxy network (if not exists)
docker network create proxy

# Start Traefik (if not running)
cd traefik && docker-compose up -d && cd ..

# Deploy MCP Proxy
docker-compose up -d

6. Verificar el Despliegue

# Check if services are running
docker-compose ps

# Test main endpoints
curl -s https://mcp.your-domain.com/health
curl -s https://mcp.your-domain.com/listmcp

# Test individual MCP server subdomains
curl -s https://memory.mcp.your-domain.com/health
curl -s https://sequential-thinking.mcp.your-domain.com/health

7. Agregar a Claude.ai

Abre Claude.ai (requiere plan Pro/Team/Enterprise)
Ve a Configuración → Integraciones
Haz clic en "Agregar más" → "Integración personalizada"
Agrega tus URLs de servidor MCP:
- https://memory.mcp.your-domain.com/sse
- https://sequential-thinking.mcp.your-domain.com/sse
- https://notion.mcp.your-domain.com/sse

Solución de Problemas

Problemas de DNS

# Test DNS resolution
nslookup memory.mcp.your-domain.com
dig *.mcp.your-domain.com

# Should resolve to your server IP

Problemas de Certificado SSL

# Check Traefik logs
docker logs traefik

# Check certificate generation
docker exec traefik cat /acme.json

Problemas del Servidor MCP

# Check proxy logs
docker logs remote-mcp-proxy

# Test individual server tools
curl -s https://mcp.your-domain.com/listtools/memory

Problemas de Conexión con Claude.ai

Verifica el formato de URL: https://server.mcp.domain.com/sse
Comprueba la autenticación (si es necesaria)
Asegúrate de que DNS y SSL funcionen
Prueba primero con el navegador

Variables de Entorno

DOMAIN: Tu dominio base (requerido)
MCP_DOMAIN: Dominio de anulación para el enrutamiento MCP (opcional)
PORT: Puerto del servidor HTTP (predeterminado: 8080)

Comandos de Configuración Dinámica

# View current servers
jq '.mcpServers | keys' config.json

# Generate and view routing configuration  
make generate
cat docker-compose.yml

# View logs for all services
make logs

# Quick restart after config changes
make restart

# Add new MCP server workflow:
# 1. Edit config.json - add new server
# 2. Run: make restart
# 3. New URL automatically available: https://newserver.mcp.domain.com/sse
# 4. All SSL, routing, service discovery handled automatically

# Update to latest version
docker-compose pull && make up

🏗️ Arquitectura Técnica

config.json → gomplate → docker-compose.yml → Traefik → Claude.ai
     ↓            ↓              ↓               ↓          ↓
   Servers    Templates    Container Labels  SSL Routes  Integration

Flujo de trabajo:

config.json: Define servidores MCP (fuente única de verdad)
gomplate: Motor de plantillas que genera docker-compose.yml
Etiquetas de Traefik: Cada servidor obtiene reglas de enrutamiento automáticas
SSL: Generación automática de certificados para subdominios
Claude.ai: URLs listas para usar sin configuración manual

📁 Archivos de Configuración Dinámica

remote-mcp-proxy/
├── config.json                    # ← MCP server definitions (edit this)
├── .env                          # ← Domain configuration
├── docker-compose.yml.template   # ← Template for generation
├── docker-compose.yml           # ← Generated automatically (don't edit)
├── Makefile                     # ← Build automation
└── ...

Archivos Clave:

Editar: config.json, .env
Generados automáticamente: docker-compose.yml
Usar: Comandos make para todas las operaciones

Desarrollo

Requisitos Previos

Go 1.21 o posterior
Docker
Dependencias de tus servidores MCP (Node.js, Python, etc.)

Desarrollo Local

# Clone the repository
git clone <repository-url>
cd remote-mcp-proxy

# Install Go dependencies
go mod tidy

# Build locally
go build -o remote-mcp-proxy .

# Run locally (requires config.json at /app/config.json)
./remote-mcp-proxy

# Or build and run with Docker
docker build -t remote-mcp-proxy .
docker run -v $(pwd)/config.json:/app/config.json -p 8080:8080 remote-mcp-proxy

Comandos de Desarrollo

Compilar: go build -o remote-mcp-proxy .
Ejecutar: ./remote-mcp-proxy
Probar: go test ./...
Lint: go fmt ./... y go vet ./...
Dependencias: go mod tidy

Pruebas

El Proxy MCP Remoto incluye pruebas completas para garantizar confiabilidad y precisión.

Prueba Rápida

# Run all tests
./test/run-tests.sh

Pruebas Manuales

# Unit tests only
go test -v ./protocol ./mcp ./proxy

# Integration tests
go test -v .

# Tests with coverage
go test -cover ./...

# Short tests (skip integration)
go test -short ./...

# Benchmarks
go test -bench=. -benchmem ./...

Configuraciones de Prueba

Se proporcionan varias configuraciones de prueba en el directorio test/:

test/minimal-config.json: Servidor echo básico para pruebas
test/development-config.json: Servidores MCP comunes para desarrollo
test/production-config.json: Ejemplos de servidores de producción
test/config.json: Configuración completa de la suite de pruebas

Pruebas con Diferentes Configuraciones

# Test with minimal config
CONFIG_PATH=./test/minimal-config.json ./remote-mcp-proxy

# Test with development servers (requires npm packages)
CONFIG_PATH=./test/development-config.json ./remote-mcp-proxy

# Test specific functionality
curl http://localhost:8080/health
curl -X GET http://localhost:8080/simple-echo/sse \
  -H "Accept: text/event-stream"

Cobertura de Pruebas

La suite de pruebas cubre:

Traducción de Protocolo: Conversión de mensajes JSON-RPC ↔ MCP Remoto
Gestión de Conexiones: Manejo de sesiones, tiempos de espera, limpieza
Manejo de Errores: Solicitudes inválidas, fallos de servidor, problemas de red
Concurrencia: Múltiples conexiones simultáneas
Autenticación: Validación de tokens y CORS
Comprobaciones de Salud: Monitoreo de estado del servidor
Integración: Pruebas de flujo de trabajo de extremo a extremo

Pruebas CI/CD

Para pruebas automatizadas en entornos CI:

# Install dependencies
go mod download

# Run tests with XML output (for CI)
go test -v ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# Static analysis
go vet ./...
go fmt ./...

Agregar Nuevos Servidores MCP

Agrega la configuración del servidor a config.json.
Reinicia el contenedor del proxy
El nuevo servidor estará disponible en /{server-name}/sse

Arquitectura

El proxy está construido en Go y consiste en:

Servidor Proxy HTTP: Maneja solicitudes MCP Remotas entrantes usando el enrutador Gorilla Mux
Gestor de Procesos MCP: Inicia y gestiona procesos de servidor MCP locales con monitoreo de salud
Traductor de Protocolo: Convierte entre protocolos HTTP/SSE y MCP JSON-RPC
Cargador de Configuración: Lee y valida configuraciones de servidor MCP (formato claude_desktop_config.json)
Manejador SSE: Implementa Server-Sent Events para comunicación MCP Remota en tiempo real

Pila Tecnológica

Go 1.21: Lenguaje central para rendimiento y concurrencia
Gorilla Mux: Enrutamiento HTTP y selección de servidor basada en rutas
Biblioteca Estándar: Gestión de procesos (os/exec), HTTP/SSE, manejo de JSON
Alpine Linux: Imagen base Docker mínima para despliegue en producción

Implementación del Protocolo MCP Remoto

El proxy implementa la especificación del protocolo MCP Remoto para habilitar la integración con Claude.ai:

Flujo del Protocolo

Autenticación OAuth 2.0: Claude.ai se autentica usando tokens Bearer mediante Registro Dinámico de Clientes OAuth 2.0
Handshake de Inicialización: Solicitud POST sincrónica a /{server}/sse con mensaje de inicialización
Gestión de Sesiones: Las sesiones se rastrean usando el encabezado Mcp-Session-Id y se marcan como inicializadas inmediatamente después del handshake exitoso
Descubrimiento de Herramientas: Las solicitudes posteriores usan la misma sesión para descubrir y llamar herramientas
Comunicación SSE: Server-Sent Events para entrega de mensajes en tiempo real (solicitudes futuras)

Detalles Críticos de Implementación

Inicialización Síncrona: A diferencia de los servidores MCP locales, Claude.ai espera una respuesta JSON sincrónica a la solicitud POST de inicialización, no una respuesta SSE asíncrona.

Inicialización de Sesión: Las sesiones DEBEN marcarse como inicializadas inmediatamente después de una respuesta exitosa del servidor MCP. Esperar una notificación separada de "inicializado" hará que el descubrimiento de herramientas falle. Concurrencia Stdio: El acceso a la salida estándar del servidor MCP se serializa usando un readMu mutex dedicado para evitar bloqueos cuando múltiples solicitudes de Claude.ai acceden al mismo servidor simultáneamente.

Manejo de tiempos de espera: Tiempo de espera de 30 segundos para respuestas de inicialización para acomodar servidores MCP basados en npm lentos. Tiempos más cortos provocan errores de "context deadline exceeded".

Normalización de nombres de herramientas: Los nombres de las herramientas se convierten automáticamente de formato con guiones (API-get-user) a snake_case (api_get_user) para compatibilidad con Claude.ai, con transformación bidireccional para llamadas a herramientas.

📊 Monitoreo, Verificaciones de Salud y Gestión de Recursos

El proxy incluye características integrales de monitoreo y estabilidad diseñadas para prevenir cuelgues del servidor y garantizar una operación confiable.

🔍 Monitoreo de Salud y Auto-Recuperación

Verificaciones de salud proactivas: El proxy monitorea continuamente todos los servidores MCP con verificaciones periódicas de ping cada 30 segundos.

# Check overall health
curl https://mcp.your-domain.com/health
# Response: {"status":"healthy"}

# Get detailed health status for all MCP servers
curl https://mcp.your-domain.com/health/servers
# Response: {
#   "timestamp": "2025-06-26T10:30:00Z",
#   "servers": {
#     "memory": {
#       "name": "memory",
#       "status": "healthy",
#       "lastCheck": "2025-06-26T10:29:45Z",
#       "responseTimeMs": 120,
#       "consecutiveFails": 0,
#       "restartCount": 0
#     }
#   },
#   "summary": {
#     "total": 4,
#     "healthy": 3,
#     "unhealthy": 1,
#     "unknown": 0
#   }
# }

Recuperación automática: Cuando los servidores dejan de responder:

✅ Detección temprana: 3 verificaciones de salud fallidas consecutivas activan la recuperación
✅ Reinicio inteligente: Reinicio automático del servidor con limpieza ordenada
✅ Límites de reinicio: Máximo 3 reinicios por ventana de 5 minutos para evitar bucles
✅ Seguimiento de estado: Historial de salud completo y seguimiento de errores

📈 Monitoreo de Recursos y Alertas

Seguimiento de recursos en tiempo real: Monitoreo del uso de memoria y CPU de todos los procesos MCP.

# Get current resource usage for all MCP processes
curl https://mcp.your-domain.com/health/resources
# Response: {
#   "timestamp": "2025-06-26T10:30:00Z",
#   "processes": [
#     {
#       "pid": 123,
#       "name": "memory-server",
#       "memoryMB": 145.2,
#       "cpuPercent": 2.1,
#       "virtualMB": 512.0,
#       "residentMB": 145.2
#     }
#   ],
#   "summary": {
#     "processCount": 4,
#     "totalMemoryMB": 580.5,
#     "totalCPU": 8.3,
#     "averageMemoryMB": 145.1,
#     "averageCPU": 2.1
#   }
# }

Umbrales de alerta:

🚨 Alerta de memoria: >500MB por proceso
🚨 Alerta de CPU: >80% de uso de CPU por proceso
📊 Registro: Resúmenes de recursos registrados cada minuto

🛡️ Gestión de Recursos y Límites de Contenedor

Límites de recursos del contenedor: Previenen el agotamiento de recursos que puede causar cuelgues del servidor.

# Docker Compose Resource Configuration
deploy:
  resources:
    limits:
      memory: 2G        # Maximum memory allocation
      cpus: '2.0'       # Maximum CPU allocation
    reservations:
      memory: 512M      # Guaranteed memory
      cpus: '0.5'       # Guaranteed CPU

Beneficios:

✅ Previene OOM: Los límites de memoria previenen condiciones de falta de memoria
✅ Protección de CPU: Los límites de CPU previenen la inanición de CPU
✅ Rendimiento predecible: Las reservas de recursos aseguran un rendimiento base
✅ Estabilidad del contenedor: Mejora de la estabilidad general del sistema

📋 Gestión del Servidor y Depuración

Monitoreo de estado del servidor:

# List all configured MCP servers and their status
curl https://mcp.your-domain.com/listmcp
# Response: {
#   "count": 4,
#   "servers": [
#     {
#       "name": "memory",
#       "running": true,
#       "pid": 123,
#       "command": "npx",
#       "args": ["-y", "@modelcontextprotocol/server-memory"]
#     }
#   ]
# }

# List available tools for a specific MCP server
curl https://mcp.your-domain.com/listtools/memory
# Response: {
#   "server": "memory",
#   "response": {
#     "jsonrpc": "2.0",
#     "result": {
#       "tools": [
#         {
#           "name": "create_entities",
#           "description": "Create multiple new entities in the knowledge graph"
#         }
#       ]
#     }
#   }
# }

# Manual connection cleanup (if needed)
curl -X POST https://mcp.your-domain.com/cleanup

🔧 Registro Mejorado y Depuración

Registro estructurado: Todos los registros incluyen correlación de sesión para una mejor depuración.

Ubicaciones de registro (con montaje de volumen /logs):

📄 Registros del sistema: /logs/system.log - Operaciones del proxy y monitoreo de salud
📄 Registros del servidor MCP: /logs/mcp-{server-name}.log - Registros individuales del servidor
📄 Retención de registros: Limpieza configurable (por defecto: 24h sistema, 12h MCP)

Niveles de registro (configurados mediante variables de entorno):

# .env configuration
LOG_LEVEL_SYSTEM=INFO      # System logging level
LOG_LEVEL_MCP=DEBUG        # MCP server logging level
LOG_RETENTION_SYSTEM=24h   # System log retention
LOG_RETENTION_MCP=12h      # MCP log retention

Trazabilidad de solicitudes mejorada: Cada solicitud incluye Método, ID y SessionID para trazabilidad completa:

2025/06/26 10:30:15 [INFO] Method: initialize, ID: 0, SessionID: abc123-def456
2025/06/26 10:30:16 [INFO] Successfully received response from server memory

🚀 Configuración de Monitoreo en Producción

Integración de monitoreo externo: Use las API de salud con su stack de monitoreo.

Ejemplo de Prometheus/Grafana:

# prometheus.yml
scrape_configs:
  - job_name: 'mcp-proxy'
    static_configs:
      - targets: ['mcp.your-domain.com']
    metrics_path: '/health/resources'
    scheme: https

Monitoreo de tiempo de actividad:

# Health check endpoint for uptime monitors
https://mcp.your-domain.com/health

# Expected response: {"status":"healthy"}

Ejemplos de reglas de alerta:

Salud del servidor: Verificar /health/servers para estado no saludable
Uso de recursos: Monitorear /health/resources para violaciones de umbral
Conteo de procesos: Alertar si hay menos procesos que servidores esperados

🛠️ Solución de problemas con nuevas características

Problemas de servidores que se cuelgan en memoria (Abordados en la última versión):

Verificar estado de salud: curl https://mcp.your-domain.com/health/servers
Revisar uso de recursos: curl https://mcp.your-domain.com/health/resources
Monitorizar auto-recuperación: El verificador de salud reiniciará automáticamente los servidores colgados
Revisar registros: Consulte /logs/mcp-memory.log para análisis detallado de errores

Prevención de agotamiento de recursos:

Los límites del contenedor previenen procesos descontrolados
El monitoreo de recursos proporciona advertencia temprana
La limpieza automática de archivos de registro antiguos previene problemas de disco

Estas características de monitoreo proporcionan visibilidad integral de la salud y el rendimiento de los servidores MCP, con capacidades de recuperación automática para garantizar una operación confiable en entornos de producción.

Solución de problemas

Problemas con el botón "Conectar" de Claude.ai (RESUELTO ✅)

Problema: El botón Conectar en la configuración de MCP remoto de Claude.ai parece funcionar pero luego falla, o muestra errores de "context deadline exceeded".

Causa raíz: Esto fue causado por bloqueos stdio durante el handshake de inicialización del servidor MCP y una gestión de sesión inadecuada.

Resolución: Estos problemas críticos se han resuelto en la versión actual:

Corrección de bloqueo Stdio: Se agregó un readMu mutex dedicado para prevenir condiciones de carrera cuando múltiples solicitudes acceden a la salida estándar del mismo servidor MCP
Corrección de inicialización de sesión: Las sesiones ahora se marcan correctamente como inicializadas después del handshake exitoso
Ajuste de tiempo de espera: Se aumentó el tiempo de espera de inicialización de 10 a 30 segundos para servidores MCP basados en npm lentos

Verificación:

El botón Conectar debería funcionar de manera confiable ahora
Las herramientas deberían exponerse y ser utilizables correctamente en Claude.ai
Revise los registros para ver mensajes de "Session marked as initialized"

El servidor MCP no se inicia

Verifique el comando y los argumentos en su configuración
Verifique que las variables de entorno estén establecidas correctamente
Consulte los registros del proxy para ver errores de arranque del proceso
Asegúrese de que las dependencias necesarias estén disponibles en el contenedor

Problemas comunes con servidores MCP basados en npm:

# Check if npm packages are available
docker exec remote-mcp-proxy npm list -g

# Verify MCP server can start manually
docker exec -it remote-mcp-proxy npx -y @notionhq/notion-mcp-server

Problemas de conexión

Asegúrese de que el proxy sea accesible desde Claude.ai
Verifique que Traefik esté configurado correctamente con certificados SSL
Verifique que el DNS del dominio apunte a su servidor
Asegúrese de que los puertos 80/443 estén abiertos en su firewall

Errores de "Context Deadline Exceeded" (RESUELTO ✅)

Problema: Los registros muestran "context deadline exceeded" durante el handshake de inicialización.

Causa raíz: Esto fue causado por bloqueos stdio y tiempo de espera insuficiente para la inicialización del servidor MCP.

Resolución: Corregido en la versión actual con mutex de lectura dedicado y tiempos de espera aumentados.

Si aún ocurre:

Verifique si los procesos del servidor MCP están realmente ejecutándose: docker exec remote-mcp-proxy ps aux
Verifique que el servidor MCP responda a comunicación directa: docker exec -i remote-mcp-proxy npx -y <server> <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

Errores de sesión no inicializada (RESUELTO ✅)

Problema: Las herramientas no aparecen en Claude.ai incluso después de una conexión exitosa.

Causa raíz: Las sesiones no se marcaban como inicializadas después del handshake exitoso.

Resolución: Corregido: las sesiones ahora se marcan automáticamente como inicializadas cuando el servidor MCP responde exitosamente a la solicitud de inicialización.

Las herramientas no aparecen

Si las herramientas no aparecen después de una conexión exitosa:

Verifique las herramientas del servidor MCP:

curl https://mcp.your-domain.com/listtools/your-server-name

Verifique la normalización de nombres: Los nombres de las herramientas se convierten automáticamente a snake_case para compatibilidad con Claude.ai
Verifique las capacidades del servidor: Algunos servidores MCP pueden no exponer herramientas inmediatamente después del inicio

Depuración general de conexión

Verifique la configuración del firewall y la red
Verifique la configuración SSL/TLS para endpoints HTTPS
Pruebe el endpoint SSE directamente: curl http://localhost:8080/{server-name}/sse
Use los endpoints de monitoreo para depurar:
- Verifique si los servidores MCP están ejecutándose: curl http://localhost:8080/listmcp
- Verifique si las herramientas están disponibles: curl http://localhost:8080/listtools/{server-name}

Errores de protocolo

Confirme que su servidor MCP soporta la versión de protocolo esperada
Verifique el formato adecuado de mensajes JSON-RPC
Revise el manejo de la conexión SSE
Monitoree los registros del proxy para ver errores de traducción

Contribución

Haga un fork del repositorio
Cree una rama de características
Haga sus cambios
Pruebe con múltiples servidores MCP
Envíe un pull request

Licencia

[Agregue su licencia aquí]