O agente lê o erro
Quando uma chamada de ferramenta a um servidor MCP falha, a mensagem de erro vira parte do contexto do agente. O agente lê o erro e decide o que fazer em seguida. Deveria tentar de novo? Tentar uma abordagem diferente? Pedir ajuda ao usuário? A decisão depende inteiramente do que a mensagem de erro lhe diz.
Uma mensagem de erro que diz "Error: ECONNREFUSED" informa ao agente que uma conexão foi recusada, mas não por quê nem o que fazer a respeito. Uma mensagem de erro que diz "Error: Cannot connect to PostgreSQL at localhost:5432. The database server may not be running, or the port may be incorrect. Check that PostgreSQL is started and the connection settings match your database configuration." dá ao agente informação suficiente para explicar o problema ao usuário e sugerir correções específicas.
Bons erros viabilizam a recuperação
As melhores mensagens de erro para ferramentas consumidas por IA seguem um padrão: o que aconteceu, por que pode ter acontecido e o que poderia corrigir. "Query returned 0 rows. The table 'users' exists but may be empty, or the WHERE clause 'created_at > 2026-12-01' may not match any records. Try broadening the date range or checking the table contents." Isso dá ao agente contexto suficiente para tentar uma consulta modificada sem precisar perguntar ao usuário.
A categorização de erros também ajuda. Se o erro indica problema de permissão, o agente sabe que tentar de novo não vai resolver. Se indica um problema temporário de rede, tentar de novo pode dar certo. Se indica parâmetros inválidos, o agente pode tentar parâmetros diferentes. Categorização clara possibilita estratégias de recuperação mais inteligentes.
Erros ruins causam loops
Mensagens de erro vagas como "Internal server error" ou "Something went wrong" não dão ao agente nenhuma informação para trabalhar. Ele pode repetir a mesma chamada que falhou (gastando tokens), tentar uma abordagem ligeiramente diferente que falha pelo mesmo motivo ou desistir totalmente quando um simples ajuste de parâmetro teria resolvido o problema.
O pior padrão é quando os erros são engolidos por completo, sem retornar nenhuma indicação de que algo deu errado. O agente recebe um resultado vazio ou parcial e segue como se estivesse correto. Isso leva a erros em cascata a jusante.
Para quem constrói servidores MCP
Se você está construindo um servidor MCP, invista nas mensagens de erro. Cada caminho de erro deve retornar uma mensagem que ajude um modelo de linguagem a entender o problema e sugerir uma correção. Pense nos seus erros como instruções para um desenvolvedor júnior que não tem acesso aos seus logs nem ao seu banco de dados. O que ele precisaria saber para diagnosticar e corrigir o problema?
Inclua o contexto relevante no erro: que operação foi tentada, que parâmetros foram usados, qual era o comportamento esperado e o que de fato aconteceu. Esse contexto custa algumas linhas extras de código, mas melhora drasticamente a forma como os agentes interagem com seu servidor.
Leituras relacionadas
- Como depurar um agente de IA que continua cometendo erros
- Por que a qualidade dos servidores MCP varia tanto (e como avaliar)
- Como agentes de IA decidem quando pedir ajuda humana
Explore servidores MCP no Skillful.sh. Pesquise mais de 137.000 ferramentas de IA.