Implementar um Servidor MCP em Produção
Nesta página
Atualização de 2 de novembro de 2026 — O Le Chat é agora o Vibe. Desde 28 de maio de 2026, o Le Chat foi renomeado para Vibe (ainda em chat.mistral.ai): um único agente para trabalho e código, mantendo as suas conversas, definições e subscrições. A experiência legada do Le Chat permanece acessível no modo Chat; no modo Work, os agentes são agora competências (invocadas com
@), as memórias formam a base de conhecimento e a pesquisa aprofundada é a competência Deep Research. Os planos passaram a chamar-se Mistral Free, Pro, Team e Enterprise. Esta lição utiliza o nome Vibe; alguns menus aqui descritos podem ter alterado de nome ou localização.
Atualização de 2 de novembro de 2026 — MCP Python SDK v2. Este curso segue agora a versão 2 do SDK
mcp(2.3.0 em 2 de outubro de 2026):MCPServersubstituiFastMCP, as definições de transporte movem-se pararun()oustreamable_http_app(), e uma aplicação exposta sob um nome de anfitrião real deve declarar esse nome de anfitrião (transport_security). Esta é também a versão exigida pelo Mistral SDK: o extramistralai[agents]requermcp>=2.2.0,<3.0. Fontes: Novidades na v2 · Guia de Migração · Implementar e escalar.
Do protótipo ao servidor de produção
O seu servidor funciona localmente e o ngrok expõe-no ao mundo apenas para uma demonstração. O problema surge quando outra pessoa precisa de o utilizar: fecha o terminal, o URL deixa de funcionar e todos os conectores que os seus colegas configuraram falham. Passar para produção significa essencialmente obter um endereço estável, disponível 24 horas por dia, 7 dias por semana, servido via HTTPS. Quatro opções levam-no lá, desde a mais rápida até à mais controlada. A sua escolha depende principalmente da sensibilidade dos seus dados e do controlo que deseja ter sobre a infraestrutura.
Opção 1: Hugging Face Spaces
O Hugging Face Spaces fornece máquinas virtuais gratuitas sem GPUs, o que é mais do que suficiente para um servidor MCP que reencaminha chamadas de API. Este é o caminho mais rápido para uma implementação real: três ficheiros e um git push.
mon-mcp-space/
├── app.py # FastAPI + servidor MCP
├── requirements.txt # Dependências
└── README.md # Metadados do Space
O ficheiro app.py segue a estrutura exata que viu até agora, exceto que os valores sensíveis são lidos do ambiente — os Segredos do HF injetam-nos ali:
# app.py
"""Servidor MCP implementado no Hugging Face Spaces."""
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings
mcp = MCPServer("My Production Server")
@mcp.tool()
def hello(name: str) -> str:
"""Saudar uma pessoa.
Args:
name: O primeiro nome da pessoa
Returns:
Mensagem de saudação
"""
return f"Hello {name} from Hugging Face Spaces!"
@asynccontextmanager
async def lifespan(app: FastAPI):
async with mcp.session_manager.run():
yield
# Nome de anfitrião do Space, no formato <user>-<space>.hf.space
SPACE_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[SPACE_HOST, f"{SPACE_HOST}:*"])
api = FastAPI(lifespan=lifespan)
api.mount("/mcp-endpoint", mcp.streamable_http_app(transport_security=security))
# Para variáveis sensíveis, utilize os Segredos do HF
API_KEY = os.environ.get("MY_API_KEY", "")
A peculiaridade da plataforma reside no README, cujo cabeçalho YAML conduz à compilação do Space. O campo app_port deve corresponder à porta na qual o seu servidor está realmente à escuta; caso contrário, a implementação é bem-sucedida, mas permanece inacessível:
---
title: My MCP Server
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---
# Criar um Space em huggingface.co
# Enviar o código
git push
# O Space é implementado automaticamente
O seu endpoint torna-se então https://your-username-mon-mcp-space.hf.space/mcp-endpoint/mcp, servido via HTTPS. Resta um passo de configuração: declarar este nome de anfitrião, your-username-mon-mcp-space.hf.space, na variável MCP_PUBLIC_HOST nas definições do Space. Sem isso, o SDK rejeita todos os pedidos com um erro 421 Invalid Host header.
Opção 2: Docker
Assim que o servidor toca em dados internos, alojar na sua própria infraestrutura torna-se a regra, e o Docker é o formato padrão. O Dockerfile requer apenas algumas instruções, com a instalação de dependências colocada antes da cópia do código para aproveitar o cache de camadas durante as recompilações:
FROM python:3.12-slim
WORKDIR /app
# Instalar dependências
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copiar código
COPY . .
# Expor porta
EXPOSE 8000
# Iniciar servidor
CMD ["uvicorn", "server:api", "--host", "0.0.0.0", "--port", "8000"]
fastapi>=0.115.0
uvicorn>=0.30.0
mcp>=2.2,<3
httpx>=0.27.0 # apenas se as suas ferramentas o utilizarem: o SDK v2 já não o instala
No arranque, a opção --restart unless-stopped é o que distingue uma implementação de produção de um simples teste: sem ela, a primeira falha coloca o seu servidor offline até que alguém perceba.
# Compilar a imagem
docker build -t mon-mcp-server .
# Executar o contentor
docker run -d \
--name mcp-server \
-p 8000:8000 \
-e MY_API_KEY="secret" \
-e DATABASE_URL="postgresql://..." \
--restart unless-stopped \
mon-mcp-server
O Docker Compose torna esta configuração reproduzível e adiciona uma verificação de integridade (health check), que o orquestrador utiliza para detetar um servidor bloqueado — um processo ativo que já não responde é um cenário que os reinícios automáticos simples não cobrem:
# docker-compose.yml
version: "3.8"
services:
mcp-server:
build: .
ports:
- "8000:8000"
environment:
- MY_API_KEY=${MY_API_KEY}
- DATABASE_URL=${DATABASE_URL}
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/"]
interval: 30s
retries: 3
Opções 3 e 4: Implementações geridas
O Prefect Horizon (anteriormente FastMCP Cloud), a plataforma da equipa por trás da estrutura independente FastMCP, remove a etapa de infraestrutura: inicia sessão em horizon.prefect.io com a sua conta GitHub, escolhe o repositório e o ficheiro do servidor, e a plataforma compila e publica um URL com autenticação integrada. Destina-se a servidores escritos com essa estrutura (pip install fastmcp, from fastmcp import FastMCP), que é distinta do SDK oficial utilizado neste curso; existe um nível gratuito para projetos pessoais.
O Cloudflare Workers visa um perfil de utilização diferente: serverless, com execução o mais próxima possível do utilizador e, portanto, latência reduzida. Um modelo dedicado inicia o projeto:
# Utilizar o modelo MCP da Cloudflare
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless
Ambas as opções poupam-no de gerir certificados e reinícios, ao custo de dependência da plataforma e restrições de execução — um Worker serverless, por exemplo, não se adequa bem a um servidor com estado.
Proteger a implementação
O HTTPS é inegociável: o Vibe recusa endpoints em texto simples, e um token que viaja sobre HTTP é um token comprometido. Três caminhos levam a isso, dependendo da sua hospedagem. Um proxy reverso como o Nginx ou o Caddy colocado à frente do seu servidor, com um certificado Let’s Encrypt, cobre o caso de um servidor dedicado. Plataformas nativas da nuvem — Hugging Face, Cloudflare e a maioria dos fornecedores PaaS — fornecem HTTPS automaticamente. Um túnel, como o Cloudflare Tunnel, expõe um servidor que permanece na sua rede interna sem abrir portas.
Nenhum segredo deve aparecer no código. Note a distinção entre as duas sintaxes abaixo: os.environ["MCP_API_TOKEN"] faz com que o arranque falhe se a variável estiver em falta, o que é exatamente o comportamento desejado para um segredo obrigatório, enquanto os.environ.get() tolera a ausência para valores opcionais.
import os
# Configuração via variáveis de ambiente
API_TOKEN = os.environ["MCP_API_TOKEN"] # Obrigatório
DATABASE_URL = os.environ.get("DATABASE_URL") # Opcional
DEBUG = os.environ.get("DEBUG", "false") == "true"
Um servidor público sem limitação de taxa acaba por ficar saturado, voluntariamente ou não. Um limitador baseado em IP é suficiente na maioria dos casos:
from fastapi import FastAPI, Request
from slowapi import Limiter, _rate_limit_exceeded_handler
limiter = Limiter(key_func=lambda request: request.client.host)
api = FastAPI()
api.state.limiter = limiter
@api.middleware("http")
async def rate_limit(request: Request, call_next):
# 100 pedidos por minuto por IP
...
Ver o que está a acontecer
Em produção, já não tem o seu terminal à sua frente, e uma ferramenta que falha uma vez em cada dez só pode ser diagnosticada com registos (logs). No mínimo, instrumente a entrada, a saída e a duração de cada chamada:
import logging
import time
logger = logging.getLogger("mcp-server")
@mcp.tool()
async def my_tool(param: str) -> str:
"""A minha ferramenta com registo."""
start = time.time()
logger.info(f"Tool called with param={param}")
try:
result = await process(param)
duration = time.time() - start
logger.info(f"Tool finished in {duration:.2f}s")
return result
except Exception as e:
logger.error(f"Error in tool: {e}")
raise
Medir a duração não é um luxo: uma ferramenta que demora doze segundos a responder desencadeia tempos limite no lado do cliente e dá a impressão de um servidor avariado quando, na verdade, está a funcionar. Antes de anunciar o seu servidor, reveja os seguintes seis pontos de configuração.
- HTTPS ativo e certificado válido
- Variáveis de ambiente para todos os segredos
- Registo estruturado ativado
- Endpoint de verificação de integridade (
/ou/health) - Reinício automático em caso de falha
- Limitação de taxa configurada
Restam duas verificações, aquelas que as pessoas mais frequentemente ignoram, mas que revelam os problemas reais: um teste com o MCP Inspector lançado de fora, seguido de um teste a partir do Mistral Vibe. Um servidor que responde perfeitamente a partir da sua máquina pode ser bloqueado por uma firewall ou configuração CORS assim que for chamado de outro local.
Pontos-chave
- Hugging Face Spaces: mais rápido, gratuito, ideal para começar
- Docker: controlo total, adequado para servidores dedicados e nuvem
- Prefect Horizon (ex-FastMCP Cloud): implementação a partir do GitHub, para servidores escritos com a estrutura FastMCP
- Cloudflare Workers: serverless, baixa latência, escalável
- Proteja com HTTPS, variáveis de ambiente e limitação de taxa
- Adicione monitorização e registos para depuração em produção