{"url":"https://runzos.com/como-configurar-servidor-mcp-docker-vps/","slug":"como-configurar-servidor-mcp-docker-vps","contentType":"artigo","intent":null,"title":"Referência MCP privada com Docker em VPS: guia prático","metaDescription":"Monte uma referência MCP privada com Docker em VPS, token, logs e validação local segura. Não é integração pronta com Claude, n8n nem ambiente de produção.","publishedAt":"2026-09-01T11:07:19.000Z","updatedAt":"2026-09-01T11:07:19.000Z","contentText":"Esta referência mostra como montar um servidor MCP privado, de leitura, com Docker em uma VPS. Você precisa de VPS Linux administrada, SSH, Docker com Compose e um token aleatório. O custo depende da VPS e do domínio, portanto não é estimado aqui. O tempo também não foi medido. O exemplo não é produção nem integração pronta com Claude ou n8n. Um servidor MCP conecta clientes de IA a dados, ferramentas e workflows externos. Ele não transforma um modelo em agente confiável. Em uma VPS, entram rede, autenticação, segredos, logs e recuperação. Para uma integração local simples, stdio costuma ter menos risco. Para uma tool persistente e remota, Docker e VPS podem fazer sentido se alguém assumir essa operação.12 A ideia deste guia é a Fronteira de Ação. Cada tool deve explicitar o que o agente pode fazer, com qual identidade, em quais dados e com qual registro. A VPS compra controle operacional. Ela não compra autonomia nem segurança automática. MCP não é um agente: onde ele entra O Model Context Protocol é um protocolo aberto para ligar aplicações de IA a fontes externas de dados, ferramentas e workflows. Ele usa mensagens JSON-RPC em UTF-8. O cliente descobre uma tool, entende seu schema e pede que o servidor a execute.111 A arquitetura mínima separa responsabilidades: cliente compatível → proxy e HTTPS → autenticação → servidor MCP → allowlist e schema → API ou dado → log Claude Code, ou outro cliente compatível, decide chamar uma ferramenta. O servidor oferece a ferramenta. A API, banco ou workflow executa apenas o trabalho permitido. Um proxy entrega HTTPS, mas não substitui escopo, validação ou auditoria. stdio local ou HTTP remoto A especificação MCP define stdio e Streamable HTTP como transportes padrão. stdio liga processos locais pela entrada e saída padrão. Streamable HTTP atende cliente e servidor remotos. Publicar HTTP muda a responsabilidade sobre rede e autorização.2 Critério stdio local Streamable HTTP em VPS Alcance Cliente e processo na mesma máquina. Cliente e servidor podem ficar separados. Exposição Não publica endpoint. Exige proxy, TLS, firewall e autenticação. Operação Menos componentes para atualizar. Inclui domínio, containers, logs e restore. Cenário Teste, uso individual e tool local. Automação persistente com responsável operacional. Comece com stdio quando estiver validando uma tool, quando há um único usuário ou quando webhook e API existentes já resolvem a integração. HTTP remoto é justificável quando a tool precisa sobreviver ao notebook ou atender cliente remoto. A documentação do MCP diferencia stdio local de fluxos OAuth para servidores HTTP remotos.3 Referência MCP privada com Docker O exemplo abaixo é didático. Ele expõe uma única tool de leitura, status_operacional, e fica acessível somente em 127.0.0.1 na VPS. Ele serve para revisar Docker, secret, autorização e logs antes de conectar uma API real. Não é servidor de produção, não inclui proxy e não configura Claude Code ou n8n. 1. Crie a pasta e o secret fora do Git Crie uma pasta restrita. Guarde o token em cofre apropriado e não o cole em Git, logs ou capturas de tela. mkdir -p ~/mcp-status/secretscd ~/mcp-statusumask 077openssl rand -hex 32 > secrets/mcp_token.txtprintf \"secrets/\\n\" > .gitignore O Compose permite conceder secrets explicitamente aos serviços. Para aplicações que suportam essa leitura, a documentação do Docker recomenda secrets em vez de variável de ambiente para dados sensíveis.7 2. Salve o servidor de leitura Crie server.py. O código não acessa banco, shell, ERP nem API. Essa limitação mantém a Fronteira de Ação pequena. import jsonfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServerTOKEN_PATH = \"/run/secrets/mcp_token\"with open(TOKEN_PATH, encoding=\"utf-8\") as secret_file: TOKEN = secret_file.read().strip()TOOLS = [{ \"name\": \"status_operacional\", \"description\": \"Retorna o estado não sensível da referência MCP.\", \"inputSchema\": {\"type\": \"object\", \"properties\": {}, \"additionalProperties\": False},}]def response(request_id, result=None, error=None): body = {\"jsonrpc\": \"2.0\", \"id\": request_id} body[\"error\" if error else \"result\"] = error if error else result return bodyclass MCPHandler(BaseHTTPRequestHandler): def log_message(self, fmt, *args): print(\"mcp_http\", self.client_address[0], fmt % args, flush=True) def do_POST(self): if self.path != \"/mcp\": self.send_error(404) return if self.headers.get(\"Authorization\") != f\"Bearer {TOKEN}\": self._send(401, {\"error\": \"unauthorized\"}) return try: payload = json.loads(self.rfile.read(int(self.headers[\"Content-Length\"]))) request_id = payload.get(\"id\") method = payload[\"method\"] except (KeyError, ValueError, json.JSONDecodeError): self._send(400, response(None, error={\"code\": -32600, \"message\": \"Invalid Request\"})) return if method == \"initialize\": result = {\"protocolVersion\": payload.get(\"params\", {}).get(\"protocolVersion\", \"2025-11-25\"), \"capabilities\": {\"tools\": {}}, \"serverInfo\": {\"name\": \"mcp-status\", \"version\": \"0.1.0\"}} self._send(200, response(request_id, result)) elif method == \"tools/list\": self._send(200, response(request_id, {\"tools\": TOOLS})) elif method == \"tools/call\" and payload.get(\"params\", {}).get(\"name\") == \"status_operacional\": self._send(200, response(request_id, {\"content\": [{\"type\": \"text\", \"text\": \"status=ok; escopo=leitura\"}]})) else: self._send(200, response(request_id, error={\"code\": -32601, \"message\": \"Method not found\"})) def _send(self, status, body): raw = json.dumps(body).encode(\"utf-8\") self.send_response(status) self.send_header(\"Content-Type\", \"application/json\") self.send_header(\"Content-Length\", str(len(raw))) self.end_headers() self.wfile.write(raw)ThreadingHTTPServer((\"0.0.0.0\", 8080), MCPHandler).serve_forever() Crie Dockerfile no mesmo diretório: FROM python:3.12-alpineWORKDIR /appCOPY server.py /app/server.pyUSER 65534CMD [\"python\", \"/app/server.py\"] 3. Use Compose com bind local Salve como compose.yaml. O bind 127.0.0.1:8080:8080 impede acesso público direto durante a referência. services: mcp-server: build: . restart: unless-stopped read_only: true tmpfs: - /tmp ports: - \"127.0.0.1:8080:8080\" secrets: - source: mcp_token target: mcp_token security_opt: - no-new-privileges:truesecrets: mcp_token: file: ./secrets/mcp_token.txt Suba o container e veja os logs: docker compose up -d --builddocker compose psdocker compose logs --tail=50 mcp-server Container em execução só confirma que o processo iniciou. Não prova backup, TLS ou autorização.8 4. Valide recusa e chamada permitida Leia o token apenas para montar o cabeçalho no shell atual. A primeira chamada é um POST JSON sem Authorization; pelo código, ela deve devolver 401. As seguintes usam o token lido em $TOKEN. Elas devem devolver JSON-RPC com status_operacional e status=ok; escopo=leitura. TOKEN=\"$(