Escrever um servidor MCP

O primeiro servidor MCP que escrevemos raramente funciona de primeira, e quase nunca pelo motivo que imaginamos. O problema não é o protocolo: as bibliotecas cuidam dele. É um print de depuração que cai na saída padrão e destrói o fluxo JSON-RPC; é uma ferramenta que lança uma exceção em vez de devolver um erro legível; é um servidor que inicia perfeitamente na mão, mas que o host não consegue executar porque não encontra o interpretador do ambiente virtual correto.

Esta lição constrói um servidor completo — duas ferramentas e um recurso em um domínio de faturamento — e depois o testa sem agente, sem modelo e sem host. A ordem importa: enquanto você não tiver visto suas respostas JSON-RPC com seus próprios olhos, conectar um agente a ele equivale a depurar dois sistemas não determinísticos ao mesmo tempo. Um servidor MCP é um programa comum, é testado como um programa comum, e é justamente isso que torna o protocolo agradável de implementar.

Preparação

python -m venv .venv
.venv/bin/pip install "mcp[cli]>=1.9"

O pacote oficial oferece dois níveis de API. O FastMCP gera os schemas JSON a partir das suas anotações de tipo e das suas docstrings; o servidor de baixo nível deixa você escrever à mão os handlers de tools/list e tools/call. Use o primeiro, a menos que precise explicitamente de controle total sobre os schemas.