Problemas comuns

`401` não é a mesma coisa que `403`

Quando uma ferramenta falha por autorização, o servidor MCP devolve um erro com metadados específicos (mcp/www_authenticate, com o resource_metadata e a lista de scopes) para que o cliente saiba o que fazer. Os dois códigos significam coisas diferentes e pedem ações diferentes:

Código	O que significa	O que fazer
`401` (`invalid_token`)	Não há credencial, a credencial é inválida, ou a hackÜ a recusou, ela expirou, foi revogada, deu timeout ou falhou.	Autorizar de novo pelo fluxo OAuth do cliente. Não adianta repetir a mesma chamada.
`403` (`insufficient_scope`)	A credencial é válida, mas não traz o scope de que aquela ferramenta precisa.	É uma decisão de configuração, não um erro passageiro: dizer qual scope está faltando e pedir que o adicionem à credencial. Repetir não muda nada.

Um detalhe que não é evidente: se a hackÜ recusa a credencial, não responde, ou demora demais, o servidor MCP também devolve 401 — ele não assume que a falha é de scope. Veja a métrica do backend antes de supor que o problema é a credencial.

Se o cliente diz que a credencial foi recusada

Se é uma conexão OAuth (Codex, o app do ChatGPT, um connector): é preciso autorizar de novo pelo cliente. Nunca cole tokens nem senhas no chat — o fluxo abre o navegador justamente para isso.

O `409` ao pedir um relatório não é um erro

request_report recusa um pedido se já existe um idêntico sendo construído, com 409 e este detalhe:

{
  "detail": "That report was already requested and is still being built. Wait for it rather than asking again.",
  "report_id": "...",
  "requested_at": "..."
}

Isso não é uma falha e não é para repetir: é para dizer à pessoa que espere o que já está em andamento. list_reports mostra o estado dele (ready: true|false) para você saber quando ficou pronto.

Listar tentativas de avaliação exige delimitar

list_evaluation_attempts exige evaluation_id ou user_id — não existe “me traga todas as tentativas”. Uma única empresa real tem 250.244 tentativas registradas; sem delimitar não há página razoável para mostrar. Pegue o id em list_evaluations (por avaliação) ou em list_users (por pessoa) antes de chamá-la.