Remote MCP Proxy

Um proxy baseado em Docker para acessar servidores MCP locais através da interface web do Claude usando o protocolo Remote MCP.

GitHub

Experimente este MCPPatrocinado

Documentação

Remote MCP Proxy

Use seus servidores MCP favoritos em qualquer lugar, sem complicação. Este projeto empacota um pequeno proxy em Go que permite conectar servidores MCP locais ou experimentais ao Claude.ai e ao aplicativo móvel. Mesmo que um servidor ainda não seja oficialmente "remoto", este proxy o expõe por meio do novo protocolo Remote MCP do Claude, para que você possa começar a integrar imediatamente.

Por que isso existe

Os servidores MCP existentes geralmente rodam apenas no seu desktop, tornando impossível usá-los com a interface web do Claude ou com o aplicativo do celular. O protocolo Remote MCP resolve isso, mas nem todos os servidores o suportam ainda. Este proxy preenche essa lacuna para que você possa experimentar imediatamente.

Como funciona

Execute o proxy no Docker e ele irá:

Iniciar e monitorar seus servidores MCP locais automaticamente
Converter o tráfego entre HTTP/SSE e o padrão MCP JSON-RPC
Hospedar vários servidores MCP ao mesmo tempo em diferentes caminhos de URL
Reutilizar o formato familiar claude_desktop_config.json
Encerrar de forma limpa e limpar qualquer processo gerado
Expor um endpoint /health para que você possa verificar o status rapidamente

🚀 Sistema de Configuração Dinâmica

Este proxy agora apresenta geração automática de roteamento de subdomínio a partir do seu arquivo config.json. Basta definir seus servidores MCP em JSON, e o sistema cria automaticamente as regras de roteamento Traefik para cada servidor.

⚡ Início Rápido

# 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

Principais Recursos

✅ Roteamento Dinâmico de Subdomínio: Cada servidor recebe {server}.mcp.{domain}/sse
✅ Integração Automática com Traefik: Rotas geradas automaticamente
✅ Escala Fácil: Adicione servidores editando apenas o JSON
✅ Pronto para Produção: SSL adequado, balanceamento de carga, descoberta de serviços

Início Rápido

1. Criar Arquivo de Configuração

Crie um arquivo config.json descrevendo seus servidores MCP (mesmo formato do 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. Implantar com Configuração Dinâmica

Opção A: Fluxo de Trabalho Automatizado com 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

Opção B: Implantação Manual com 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 Variáveis de Ambiente

A configuração do compose espera /home/pezzos/docker/config/secrets/remote_mcp_proxy.env. O arquivo é vinculado simbolicamente neste diretório 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

Exemplo de conteúdo:

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

4. Usar Docker Compose com Traefik

docker-compose up -d

Isso implantará o serviço com integração de proxy reverso Traefik, tornando-o acessível em mcp.{DOMAIN} com HTTPS automático.

5. Configurar DNS Wildcard (Obrigatório)

Configure DNS wildcard para roteamento dinâmico de subdomínio:

Exemplo de Configuração DNS (Cloudflare):

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

Para outros provedores de DNS, crie um registro A:

*.mcp.your-domain.com    A    YOUR_SERVER_IP

6. Configurar Claude.ai

Abra o Claude.ai (requer plano Pro, Max, Teams ou Enterprise) e adicione suas URLs de proxy geradas automaticamente em Configurações > Integrações:

URLs Geradas Automaticamente (com base no seu 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

✅ Status da Integração com Claude.ai: O botão Conectar agora funciona de forma confiável! O proxy suporta totalmente a integração Remote MCP do Claude.ai com gerenciamento adequado de sessão e descoberta de ferramentas.

🔄 Adicionando Novos Servidores MCP

1. Edite o config.json:

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

2. Reimplante:

make restart

3. Use imediatamente:

Nova URL: https://new-server.mcp.your-domain.com/sse
SSL, roteamento e balanceamento de carga configurados automaticamente

Endpoints de Depuração: Use estes endpoints para verificar se seus servidores MCP estão funcionando:

Verificar status do servidor: https://mcp.your-domain.com/listmcp
Verificar ferramentas disponíveis: https://mcp.your-domain.com/listtools/your-server-name

🌐 Estrutura de URL Dinâmica

Formato Gerado Automaticamente: Cada servidor MCP está disponível automaticamente em:

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

Exemplos (do seu config.json):

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

Onde {DOMAIN} é definido no seu arquivo .env e {server-name} corresponde à chave no seu arquivo config.json.

🔧 Referência de Comandos Make

Comando	Descrição
`make help`	Mostrar todos os comandos disponíveis
`make install-deps`	Instalar dependência gomplate
`make generate`	Gerar docker-compose.yml a partir do config.json
`make build`	Construir imagens Docker
`make up`	Gerar configuração e iniciar serviços
`make down`	Parar e remover serviços
`make restart`	Reiniciar serviços com nova configuração
`make logs`	Mostrar logs dos serviços
`make clean`	Remover arquivos gerados

Por que Geração Dinâmica de Subdomínio?

O Claude.ai espera endpoints Remote MCP no nível raiz (/sse), não roteamento baseado em caminho. Esta abordagem automatizada de subdomínio:

✅ Corresponde ao formato padrão Remote MCP
✅ Escala automaticamente com mudanças no config.json
✅ Fornece separação limpa entre servidores
✅ Elimina configuração manual do Traefik
✅ Permite implantação instantânea de novos servidores

Configuração

O proxy usa o mesmo formato de configuração do claude_desktop_config.json do Claude Desktop:

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

Variáveis de Ambiente

Variáveis de Ambiente do Docker Compose

As seguintes variáveis de ambiente são usadas pela configuração do Docker Compose:

DOMAIN: Seu nome de domínio base (ex.: example.com). Os servidores MCP estarão acessíveis em {server}.mcp.{DOMAIN}

Variáveis de Ambiente do Servidor MCP

Defina variáveis de ambiente para seus servidores MCP na seção env do config.json
Armazene segredos com segurança e referencie-os na sua implantação Docker
O proxy passará essas variáveis de ambiente para os processos MCP gerados

Docker Compose com Traefik

Configuração de Subdomínio Wildcard

O serviço está configurado para funcionar com o proxy reverso Traefik para HTTPS automático e roteamento de subdomínio 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

Pontos-chave de Configuração:

Regra Wildcard: Host(\*.mcp.${DOMAIN}) captura todos os subdomínios como memory.mcp.domain.com
SSL Dinâmico: O Traefik gera automaticamente certificados SSL para novos subdomínios
Domínio Principal: mcp.${DOMAIN} para endpoints utilitários (/health, /listmcp)
Requisito de DNS: O registro DNS wildcard *.mcp.domain.com deve ser configurado

Guia de Configuração Completo

Pré-requisitos

Docker e Docker Compose instalados
Nome de domínio com controle de DNS
Proxy reverso Traefik em execução (ou disposição para configurá-lo)

Configuração Passo a Passo

1. Clonar e Configurar

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

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

2. Configurar Seus Servidores MCP

Edite config.json com seus servidores MCP desejados:

{
  "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 (Passo Crítico)

Para Cloudflare:

Vá para as configurações de DNS do seu domínio
Adicione um novo registro:
- Tipo: A
- Nome: *.mcp
- Conteúdo: O endereço IP do seu servidor
- Status do proxy: Proxied (nuvem laranja)

Para outros provedores de DNS: Crie um registro A wildcard: *.mcp.your-domain.com → YOUR_SERVER_IP

4. Configurar Traefik (Se Ainda Não Estiver em Execução)

Crie 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

Crie 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. Implantar o MCP Proxy

# 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 a Implantação

# 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. Adicionar ao Claude.ai

Abra o Claude.ai (requer plano Pro/Team/Enterprise)
Vá para Configurações → Integrações
Clique em "Adicionar mais" → "Integração personalizada"
Adicione suas URLs do servidor MCP:
- https://memory.mcp.your-domain.com/sse
- https://sequential-thinking.mcp.your-domain.com/sse
- https://notion.mcp.your-domain.com/sse

Solução 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 com o 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 Conexão com Claude.ai

Verifique o formato da URL: https://server.mcp.domain.com/sse
Verifique a autenticação (se necessário)
Garanta que DNS e SSL estejam funcionando
Teste primeiro no navegador

Variáveis de Ambiente

DOMAIN: Seu domínio base (obrigatório)
MCP_DOMAIN: Domínio de substituição para roteamento MCP (opcional)
PORT: Porta do servidor HTTP (padrão: 8080)

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

🏗️ Arquitetura Técnica

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

Fluxo de Trabalho:

config.json: Defina servidores MCP (fonte única de verdade)
gomplate: Mecanismo de template gera docker-compose.yml
Rótulos Traefik: Cada servidor recebe regras de roteamento automáticas
SSL: Geração automática de certificados para subdomínios
Claude.ai: URLs prontas para uso com zero configuração manual

📁 Arquivos de Configuração 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
└── ...

Arquivos-chave:

Editar: config.json, .env
Gerados automaticamente: docker-compose.yml
Usar: comandos make para todas as operações

Desenvolvimento

Pré-requisitos

Go 1.21 ou posterior
Docker
Dependências dos seus servidores MCP (Node.js, Python, etc.)

Desenvolvimento 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 Desenvolvimento

Build: go build -o remote-mcp-proxy .
Executar: ./remote-mcp-proxy
Testar: go test ./...
Lint: go fmt ./... e go vet ./...
Dependências: go mod tidy

Testes

O Remote MCP Proxy inclui testes abrangentes para garantir confiabilidade e correção.

Teste Rápido

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

Teste Manual

# 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 ./...

Configurações de Teste

Várias configurações de teste são fornecidas no diretório test/:

test/minimal-config.json: Servidor echo básico para testes
test/development-config.json: Servidores MCP comuns para desenvolvimento
test/production-config.json: Exemplos de servidores de produção
test/config.json: Configuração completa da suíte de testes

Testando com Diferentes Configurações

# 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 Testes

A suíte de testes cobre:

Tradução de Protocolo: Conversão de mensagens JSON-RPC ↔ Remote MCP
Gerenciamento de Conexão: Tratamento de sessão, timeouts, limpeza
Tratamento de Erros: Requisições inválidas, falhas de servidor, problemas de rede
Concorrência: Múltiplas conexões simultâneas
Autenticação: Validação de token e CORS
Health Checks: Monitoramento de status do servidor
Integração: Teste de fluxo de trabalho ponta a ponta

Testes CI/CD

Para testes automatizados em ambientes de 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 ./...

Adicionando Novos Servidores MCP

Adicione a configuração do servidor ao config.json
Reinicie o contêiner do proxy
O novo servidor estará disponível em /{server-name}/sse

Arquitetura

O proxy é construído em Go e consiste em:

Servidor Proxy HTTP: Lida com requisições Remote MCP recebidas usando o roteador Gorilla Mux
Gerenciador de Processos MCP: Inicia e gerencia processos de servidores MCP locais com monitoramento de saúde
Tradutor de Protocolo: Converte entre protocolos HTTP/SSE e MCP JSON-RPC
Carregador de Configuração: Lê e valida configurações de servidores MCP (formato claude_desktop_config.json)
Manipulador SSE: Implementa Server-Sent Events para comunicação Remote MCP em tempo real

Stack de Tecnologia

Go 1.21: Linguagem principal para desempenho e concorrência
Gorilla Mux: Roteamento HTTP e seleção de servidor baseada em caminho
Biblioteca Padrão: Gerenciamento de processos (os/exec), HTTP/SSE, manipulação de JSON
Alpine Linux: Imagem base Docker mínima para implantação em produção

Implementação do Protocolo Remote MCP

O proxy implementa a especificação do protocolo Remote MCP para permitir a integração com Claude.ai:

Fluxo do Protocolo

Autenticação OAuth 2.0: Claude.ai autentica usando tokens Bearer via Registro Dinâmico de Cliente OAuth 2.0
Handshake de Inicialização: Requisição POST síncrona para /{server}/sse com mensagem de inicialização
Gerenciamento de Sessão: Sessões são rastreadas usando o cabeçalho Mcp-Session-Id e marcadas como inicializadas imediatamente após o handshake bem-sucedido
Descoberta de Ferramentas: Requisições subsequentes usam a mesma sessão para descobrir e chamar ferramentas
Comunicação SSE: Server-Sent Events para entrega de mensagens em tempo real (requisições futuras)

Detalhes Críticos de Implementação

Inicialização Síncrona: Diferente dos servidores MCP locais, o Claude.ai espera uma resposta JSON síncrona para a requisição POST de inicialização, não uma resposta SSE assíncrona.

Inicialização de Sessão: Sessões DEVEM ser marcadas como inicializadas imediatamente após uma resposta bem-sucedida do servidor MCP. Aguardar uma notificação separada de "inicializado" fará com que a descoberta de ferramentas falhe. Concorrência Stdio: O acesso ao stdout do servidor MCP é serializado usando um mutex dedicado readMu para evitar deadlocks quando múltiplas solicitações do Claude.ai acessam o mesmo servidor simultaneamente.

Tratamento de Timeout: Timeout de 30 segundos para respostas de inicialização para acomodar servidores MCP baseados em npm lentos. Timeouts mais curtos causam erros de "context deadline exceeded".

Normalização de Nomes de Ferramentas: Os nomes das ferramentas são automaticamente convertidos do formato hifenizado (API-get-user) para snake_case (api_get_user) para compatibilidade com Claude.ai, com transformação bidirecional para chamadas de ferramentas.

📊 Monitoramento, Verificações de Saúde e Gerenciamento de Recursos

O proxy inclui recursos abrangentes de monitoramento e estabilidade projetados para evitar travamentos do servidor e garantir operação confiável.

🔍 Monitoramento de Saúde e Recuperação Automática

Verificações de Saúde Proativas: O proxy monitora continuamente todos os servidores MCP com verificações periódicas de ping a 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
#   }
# }

Recuperação Automática: Quando os servidores ficam sem resposta:

✅ Detecção Precoce: 3 verificações de saúde consecutivas com falha acionam a recuperação
✅ Reinício Inteligente: Reinício automático do servidor com limpeza graciosa
✅ Limites de Reinício: Máximo de 3 reinícios por janela de 5 minutos para evitar loops
✅ Rastreamento de Status: Histórico abrangente de saúde e rastreamento de erros

📈 Monitoramento de Recursos e Alertas

Rastreamento de Recursos em Tempo Real: Monitore o uso de memória e CPU de todos os processos 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
#   }
# }

Limites de Alerta:

🚨 Alerta de Memória: >500MB por processo
🚨 Alerta de CPU: >80% de uso de CPU por processo
📊 Registro: Resumos de recursos registrados a cada minuto

🛡️ Gerenciamento de Recursos e Limites de Contêiner

Limites de Recursos do Contêiner: Previne a exaustão de recursos que pode causar travamentos do 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

Benefícios:

✅ Previne OOM: Limites de memória previnem condições de falta de memória
✅ Proteção de CPU: Limites de CPU previnem inanição de CPU
✅ Desempenho Previsível: Reservas de recursos garantem desempenho de linha de base
✅ Estabilidade do Contêiner: Melhora a estabilidade geral do sistema

📋 Gerenciamento e Depuração de Servidores

Monitoramento de Status do 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 e Depuração Aprimorados

Registro Estruturado: Todos os logs incluem correlação de sessão para melhor depuração.

Locais de Log (com montagem de volume /logs):

📄 Logs do Sistema: /logs/system.log - Operações do proxy e monitoramento de saúde
📄 Logs do Servidor MCP: /logs/mcp-{server-name}.log - Logs individuais do servidor
📄 Retenção de Logs: Limpeza configurável (padrão: 24h sistema, 12h MCP)

Níveis de Log (configurados via variáveis de ambiente):

# .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

Rastreamento Aprimorado de Solicitações: Cada solicitação inclui Método, ID e SessionID para rastreabilidade 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

🚀 Configuração de Monitoramento em Produção

Integração de Monitoramento Externo: Use as APIs de saúde com sua pilha de monitoramento.

Exemplo Prometheus/Grafana:

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

Monitoramento de Uptime:

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

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

Exemplos de Regras de Alerta:

Saúde do servidor: Verifique /health/servers para status não saudável
Uso de recursos: Monitore /health/resources para violações de limite
Contagem de processos: Alerte se houver menos processos do que servidores esperados

🛠️ Solução de Problemas com Novos Recursos

Problemas de Travamento do Servidor de Memória (Abordados na versão mais recente):

Verifique o Status de Saúde: curl https://mcp.your-domain.com/health/servers
Revise o Uso de Recursos: curl https://mcp.your-domain.com/health/resources
Monitore a Recuperação Automática: O verificador de saúde reiniciará automaticamente servidores travados
Verifique os Logs: Revise /logs/mcp-memory.log para análise detalhada de erros

Prevenção de Exaustão de Recursos:

Limites de contêiner previnem processos descontrolados
Monitoramento de recursos fornece aviso antecipado
Limpeza automática de arquivos de log antigos previne problemas de disco

Esses recursos de monitoramento fornecem visibilidade abrangente da saúde e desempenho do servidor MCP, com capacidades de recuperação automática para garantir operação confiável em ambientes de produção.

Solução de Problemas

Problemas com o Botão "Connect" do Claude.ai (RESOLVIDO ✅)

Problema: O botão Connect nas configurações do Remote MCP do Claude.ai parece funcionar, mas depois falha, ou mostra erros de "context deadline exceeded".

Causa Raiz: Isso foi causado por deadlocks de stdio durante o handshake de inicialização do servidor MCP e gerenciamento inadequado de sessão.

Resolução: Esses problemas críticos foram resolvidos na versão atual:

Correção de Deadlock Stdio: Adicionado mutex dedicado readMu para prevenir condições de corrida quando múltiplas solicitações acessam o stdout do mesmo servidor MCP
Correção de Inicialização de Sessão: As sessões agora são marcadas corretamente como inicializadas após handshake bem-sucedido
Ajuste de Timeout: Aumentado o timeout de inicialização de 10 para 30 segundos para servidores MCP baseados em npm lentos

Verificação:

O botão Connect agora deve funcionar de forma confiável
As ferramentas devem ser expostas e utilizáveis corretamente no Claude.ai
Verifique os logs para mensagens "Session marked as initialized"

Servidor MCP Não Inicia

Verifique o comando e os argumentos na sua configuração
Verifique se as variáveis de ambiente estão definidas corretamente
Veja os logs do proxy para erros de spawn de processo
Garanta que as dependências necessárias estejam disponíveis no contêiner

Problemas comuns com servidores MCP baseados em 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 Conexão

Garanta que o proxy seja acessível a partir do Claude.ai
Verifique se o Traefik está configurado corretamente com certificados SSL
Verifique se o DNS do domínio aponta para o seu servidor
Garanta que as portas 80/443 estejam abertas no seu firewall

Erros de "Context Deadline Exceeded" (RESOLVIDO ✅)

Problema: Os logs mostram "context deadline exceeded" durante o handshake de inicialização.

Causa Raiz: Isso foi causado por deadlocks de stdio e timeout insuficiente para a inicialização do servidor MCP.

Resolução: Corrigido na versão atual com mutex de leitura dedicado e timeouts aumentados.

Se ainda estiver ocorrendo:

Verifique se os processos do servidor MCP estão realmente em execução: docker exec remote-mcp-proxy ps aux
Verifique se o servidor MCP responde à comunicação direta: 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"}}}'

Erros de Sessão Não Inicializada (RESOLVIDO ✅)

Problema: Ferramentas não aparecem no Claude.ai mesmo após conexão bem-sucedida.

Causa Raiz: As sessões não estavam sendo marcadas como inicializadas após handshake bem-sucedido.

Resolução: Corrigido - as sessões agora são marcadas automaticamente como inicializadas quando o servidor MCP responde com sucesso à solicitação de inicialização.

Ferramentas Não Aparecem

Se as ferramentas não aparecerem após conexão bem-sucedida:

Verifique as ferramentas do servidor MCP:

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

Verifique a normalização de nomes de ferramentas: Os nomes das ferramentas são automaticamente convertidos para snake_case para compatibilidade com Claude.ai
Verifique as capacidades do servidor: Alguns servidores MCP podem não expor ferramentas imediatamente após a inicialização

Depuração Geral de Conexão

Verifique a configuração de firewall e rede
Verifique a configuração SSL/TLS para endpoints HTTPS
Teste o endpoint SSE diretamente: curl http://localhost:8080/{server-name}/sse
Use os endpoints de monitoramento para depurar:
- Verifique se os servidores MCP estão em execução: curl http://localhost:8080/listmcp
- Verifique se as ferramentas estão disponíveis: curl http://localhost:8080/listtools/{server-name}

Erros de Protocolo

Confirme se o seu servidor MCP suporta a versão de protocolo esperada
Verifique a formatação correta de mensagens JSON-RPC
Revise o tratamento de conexão SSE
Monitore os logs do proxy para erros de tradução

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Teste com múltiplos servidores MCP
Envie um pull request

Licença

[Adicione sua licença aqui]