Tratamento de Erros em Servidores MCP: O que eu aprendi
Achei que tinha terminado depois que meu servidor MCP rodou pela primeira vez. Ele retornou uma lista de ferramentas. Chamou uma ferramenta. Senti que tinha tido sucesso.
Eu estava errado.
Rodar um servidor MCP em produção me ensinou que os tutoriais focam no "caminho feliz" (happy path). Eles ignoram o que acontece quando as coisas quebram. Aqui está o que aprendi enquanto construía um servidor para minha base de conhecimento de 1.800 horas.
Sempre retorne conteúdo para resultados vazios A maioria dos clientes trava quando recebe uma resposta vazia. Se sua busca não encontrar nada, não retorne nada. Retorne uma mensagem de texto. Diga ao usuário por que não há resultados e quantos itens existem no seu banco de dados.
Gerencie inícios de conexão lentos Eu hospedo em um nível gratuito que entra em modo de espera (sleep). Quando ele acorda, leva 15 segundos. Muitos clientes MCP sofrem timeout antes disso. • Envie headers precocemente para manter a conexão viva. • Defina limites rígidos no tamanho da resposta. Trunque resultados grandes para não atingir os limites de timeout.
Pare de construir JSON manualmente Uma aspa dupla não escapada em um título quebrou toda a minha resposta JSON. O cliente desconectou sem erro. Use um framework como Jackson para lidar com a serialização. Deixe a biblioteca gerenciar o escape para você.
Espere autenticação inconsistente Diferentes clientes lidam com chaves de API de formas diferentes. Alguns usam headers. Alguns usam parâmetros de consulta (query parameters). Alguns não usam nenhum dos dois. • Suporte múltiplas formas de enviar chaves. • Sempre retorne um corpo de erro JSON adequado se a autenticação falhar.
Defina o Content-Length explicitamente Alguns clientes têm dificuldade com chunked encoding. Se suas respostas forem truncadas, pare de usar compressão. Pré-calcule o tamanho da sua resposta e defina o header Content-Length explicitamente.
Os Prós: • Privacidade: Apenas trechos relevantes vão para a IA. • Interoperabilidade: O servidor funciona em diferentes clientes. • Simplicidade: Meu servidor tem apenas 150 linhas de código.
Os Contras: • Ecossistema jovem: A documentação não cobre muitos casos de borda (edge cases). • Hospedagem: Você deve gerenciar seus próprios endpoints e cold starts. • Evolução: O protocolo muda com frequência.
O MCP transformou minhas notas não utilizadas em uma ferramenta útil. Ele torna meus dados disponíveis para que a IA possa fazer o trabalho pesado.
Você já construiu um servidor MCP? Quais erros você enfrentou? Deixe-me saber nos comentários.
Optional learning community: https://t.me/GyaanSetuAi