Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Implementar um Servidor MCP em Produção

Aula 12 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Do protótipo ao servidor de produção
  2. Opção 1: Hugging Face Spaces
  3. Opção 2: Docker
  4. Opções 3 e 4: Implementações geridas
  5. Proteger a implementação
  6. Ver o que está a acontecer
  7. Pontos-chave

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): MCPServer substitui FastMCP, as definições de transporte movem-se para run() ou streamable_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 extra mistralai[agents] requer mcp>=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