O viés do caminho feliz
Leia a maioria dos READMEs de servidores MCP e você vai aprender exatamente como configurar o servidor e o que ele consegue fazer em condições ideais. "Consulte qualquer banco de dados SQL." "Leia e escreva arquivos." "Pesquise na web." Essas descrições de capacidades são precisas, mas incompletas. Elas não dizem o que acontece quando as coisas saem do trilho.
O que acontece quando você consulta uma tabela com 10 milhões de linhas? O que acontece quando a conexão com o banco cai no meio da consulta? Quais tamanhos de arquivo são grandes demais para processar? Quais dialetos SQL são realmente suportados? As respostas para essas perguntas costumam ser descobertas por meio de doloroso processo de tentativa e erro.
O que a documentação de falhas deve incluir
Limitações conhecidas: "O tamanho máximo do conjunto de resultados é de 10.000 linhas. Consultas maiores serão truncadas." "Arquivos binários não são suportados e retornarão um erro." Isso define expectativas para que os usuários não percam tempo descobrindo limites por meio de falhas.
Cenários de erro comuns: "Se você ver 'connection timeout', o servidor de banco de dados pode estar inacessível. Verifique se o host e a porta na sua configuração estão corretos." Isso economiza tempo de depuração ao fornecer a explicação mais provável para erros comuns.
Casos extremos: "Consultas com colunas BLOB falharão porque dados binários não podem ser serializados em JSON." "Caminhos de arquivo com caracteres Unicode podem não funcionar no Windows." Isso evita as surpresas específicas que causam mais frustração.
O efeito de confiança
Contraintuitivamente, documentar falhas constrói confiança. Quando um README diz honestamente "este servidor funciona muito bem para consultas com menos de 10.000 linhas, mas tem dificuldade com conjuntos de resultados maiores", você confia mais no autor do que em alguém que afirma capacidades ilimitadas. Você também toma uma decisão de adoção mais bem informada.
Boa documentação de falhas é um investimento em experiência do desenvolvedor. Usuários que entendem os limites da ferramenta a usam dentro desses limites e têm uma boa experiência. Usuários que descobrem os limites por meio de falhas têm uma experiência ruim e podem migrar para uma alternativa.
Leituras relacionadas
- Por que descobrir servidores MCP é mais difícil do que parece
- Como mensagens de erro de servidores MCP afetam o comportamento do agente
- Por que a experiência do desenvolvedor importa para a adoção de ferramentas de IA
Explore servidores MCP no Skillful.sh. Pesquise mais de 137.000 ferramentas de IA.