Problemas comunes

`401` no es lo mismo que `403`

Cuando una herramienta falla por autorización, el servidor MCP devuelve un error con metadata específica (mcp/www_authenticate, con el resource_metadata y la lista de scopes) para que el cliente sepa qué hacer. Los dos códigos significan cosas distintas y piden acciones distintas:

Código	Qué significa	Qué hacer
`401` (`invalid_token`)	No hay credencial, la credencial es inválida, o hackÜ la rechazó, expiró, fue revocada, dio timeout o falló.	Volver a autorizar por el flujo OAuth del cliente. No sirve reintentar la misma llamada.
`403` (`insufficient_scope`)	La credencial es válida, pero no trae el scope que esa herramienta necesita.	Es una decisión de configuración, no un error transitorio: decir qué scope falta y pedir que se lo agreguen a la credencial. Reintentar no cambia nada.

Un detalle no evidente: si hackÜ rechaza la credencial, no responde, o tarda demasiado, el servidor MCP también devuelve 401 — no asume que la falla es de scope. Ver la métrica del backend antes de asumir que el problema es la credencial.

Si el cliente dice que la credencial fue rechazada

Si es una conexión OAuth (Codex, la app de ChatGPT, un connector): hay que volver a autorizar desde el cliente. Nunca pegar tokens ni contraseñas en el chat — el flujo abre el navegador para eso.

El `409` al pedir un reporte no es un error

request_report rechaza un pedido si ya hay uno idéntico en construcción, con 409 y este detalle:

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

Esto no es una falla y no hay que reintentar: hay que decirle a la persona que espere el que ya está en curso. list_reports muestra su estado (ready: true|false) para saber cuándo está listo.

Listar intentos de evaluación exige acotar

list_evaluation_attempts requiere evaluation_id o user_id — no hay “traeme todos los intentos”. Una sola empresa real tiene 250.244 intentos registrados; sin narrow no hay página razonable que mostrar. Sacá el id de list_evaluations (por evaluación) o de list_users (por persona) antes de llamarla.