En producción, los logs son tu única ventana al agente

Un MCP en producción es una caja negra desde el punto de vista del cliente final. El agente decide, invoca, lee el resultado, decide de nuevo. cuando algo sale mal, la única forma de entender qué pasó es la traza de logs que vos dejaste.

Si no logueás nada, en 3 días vas a tener un ticket: "el agente no asignó el turno de Em al rendezvous". Y vos no vas a saber:

• ¿Se invocó la tool?
• ¿Con qué parámetros?
• ¿Falló por validación? ¿por DB?
• ¿Cuánto tardó? (un timeout silencioso da síntomas idénticos a un crash)
• ¿Se invocó dos veces?

Logueo bien hecho responde todas esas en 30 segundos.

Los tres logs que todo handler de tool debería tener

1. tool.start al entrar. registra nombre, params, request_id de correlación.
2. tool.success justo antes del return del happy path. registra resultado clave, duración.
3. tool.error en cada path de error. registra code, params, duración.

async function handle(params) {
  const request_id = crypto.randomUUID();
  const startedAt = Date.now();
  logger.info("tool.start", { tool: "assign_shift", request_id, params });

  // ... lógica ...

  if (failure) {
    logger.warn("tool.error", {
      tool: "assign_shift",
      request_id,
      duration_ms: Date.now() - startedAt,
      code: "...",
      params,
    });
    return { ok: false, error: { code, message } };
  }

  logger.info("tool.success", {
    tool: "assign_shift",
    request_id,
    duration_ms: Date.now() - startedAt,
    result_summary: { assignment_id },
  });
  return { ok: true, assignment_id };
}

El request_id: lo que hace al log usable

Sin request_id, los logs de invocaciones concurrentes se mezclan y no podés rearmar ninguna traza. Con request_id (generado al inicio y propagado por todo el handler), un grep request_id=abc123 te trae toda la historia de esa invocación específica.

Bonus avanzado: si tu sistema tiene tracing distribuido (OpenTelemetry, etc.), request_id puede ser un trace_id que conecta con los logs de tus servicios downstream (DB, APIs externas). Esa correlación es el santo grial del debugging en sistemas distribuidos.

Qué NO loguear

• Secretos. Tokens, passwords, API keys, datos de tarjeta. Si están en params, redactalos: { token: "***" }.
• PII grueso. Mails, números de documento. Solo si el dominio lo requiere y con políticas claras.
• Bodies enormes. Imágenes en base64, JSONs de 10MB. Loguear un summary, no todo.

Tu tarea

A la derecha tenés assign_shift con validaciones pero sin logging. Agregá los logs de start, success y error en cada path. Usá request_id correlador.

Un handler sin logs es un handler que vas a tener que reescribir en cuanto falle en producción. Costo bajo, beneficio alto, hacelo desde el día 1.