Como Construir Servidores MCP Prontos para Produção com FastMCP em Python: Da Validação de Entrada Complexa com Pydantic ao Deployment ASGI

Um guia prático para estruturar, validar, proteger e implantar servidores FastMCP 3.0 usando Pydantic e ASGI.

Resumo: Fixe fastmcp>=3.0, defina ferramentas com modelos Pydantic aninhados para validação rigorosa de entrada, proteja o servidor com middleware ASGI de nível de transporte ou hooks de autenticação do FastMCP 3.0, e exponha um único ponto de entrada ASGI via Uvicorn para implantar um servidor MCP pronto para produção sobre SSE.

Estruture o Projeto e Fixe o FastMCP 3.0

Fixe fastmcp>=3.0 em pyproject.toml para que os recursos instalados correspondam ao código, depois organize o projeto como um pacote em layout src com a instância do FastMCP dentro de src/myserver/server.py e o ponto de entrada ASGI isolado em main.py na raiz.

Comece com a dependência. O FastMCP 3.0 introduziu o modelo de componentes e as APIs de implantação das quais dependemos, portanto, a restrição de versão é obrigatória. O limite inferior >=3.0 garante que você obtenha o modelo de componentes 3.0 e os auxiliares ASGI; fixar aqui evita erros em tempo de execução devido a instalações desatualizadas.

[project]
name = "myserver"
version = "0.1.0"
dependencies = [
    "fastmcp>=3.0",
]
requires-python = ">=3.10"

Use um layout src para manter os caminhos de importação explícitos e separar a implementação do servidor da superfície implantável:

.
├── pyproject.toml
├── main.py
└── src/
    └── myserver/
        ├── __init__.py
        └── server.py

Dentro de src/myserver/server.py, inicialize o servidor e defina ferramentas na instância mcp:

from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool()
def search_docs(query: str) -> str:
    ...

Mantenha main.py na raiz do projeto minimal; ele importará este objeto mcp e o exporá como uma aplicação ASGI quando cobrirmos a implantação. Essa divisão evita importações circulares e permite que você teste a lógica do servidor independentemente do transporte HTTP. Registrar ferramentas diretamente nesta instância mantém as definições colocadas com o estado do servidor. Importaremos mcp em main.py mais tarde e o envolveremos para o Uvicorn, mas a lógica central permanece dentro do pacote.

Valide Entradas Complexas com Modelos Pydantic

O FastMCP gera automaticamente o JSON Schema para os argumentos da ferramenta e valida os payloads recebidos quando você usa modelos Pydantic fortemente tipados em vez de dicionários brutos. O Pydantic rejeita dados malformados antes que sua lógica de negócios seja executada, eliminando cláusulas de guarda manuais.

Defina modelos aninhados com descrições de Field para que o esquema gerado seja auto-documentado para os clientes MCP:

from pydantic import BaseModel, Field

class SortOrder(BaseModel):
    field: str = Field(..., description="Coluna para ordenar")
    ascending: bool = Field(default=True, description="Ordenar ascendente")

class QueryRequest(BaseModel):
    table: str = Field(..., description="Nome da tabela alvo")
    filters: dict[str, str] = Field(default_factory=dict)
    sort: SortOrder | None = Field(default=None)

Aceite o modelo como um parâmetro tipado em uma função de ferramenta. O FastMCP mapeia a anotação para o protocolo MCP e injeta a instância validada:

from fastmcp import FastMCP

mcp = FastMCP("servidor-produção")

@mcp.tool()
async def run_query(request: QueryRequest) -> list[dict]:
    # O Pydantic já validou tipos e estruturas aninhadas
    return await db.fetch(request
Contexto Triplo Up
A implementação de servidores MCP prontos para produção pode ajudar empresas brasileiras a otimizar suas operações com IA. O uso de validação rigorosa e middleware de segurança melhora a confiabilidade e a segurança dos serviços. Isso é crucial em um cenário onde a integração de agentes de IA se torna cada vez mais comum.