Token Bearer dedicado para el routine Maintenance-Weekly

Qué hace

Introduce un mecanismo de autenticación alternativo en el handler MCP del workspace (functions/api/mcp/index.ts) que permite a agentes headless — concretamente el routine Maintenance-Weekly ejecutado por Claude Sonnet en claude.ai — autenticarse contra /api/mcp mediante un Bearer token dedicado, sin requerir el flujo OAuth interactivo.

Cuando el header Authorization: Bearer <token> coincide con la variable de entorno MAINTENANCE_AGENT_TOKEN, la función authenticate() devuelve { ok: true, user: 'maintenance-agent' } y cortocircuita el loop habitual de MCP_TOKENS.

Motivación

El routine Maintenance-Weekly ejecuta en modo headless dentro de claude.ai. En ese contexto el agente Sonnet únicamente tiene acceso a las tools authenticate y complete_authentication del connector MCP — las tools de trabajo (send_maintenance_email, etc.) no están disponibles hasta que el flujo OAuth se complete. Como el flujo OAuth es interactivo (requiere confirmación del usuario), el agente no puede completarlo y cae al fallback de redactar un Gmail draft manual.

Problema confirmado en los runs del 13-05-2026 y 18-05-2026.

Diseño e implementación

Lógica añadida en functions/api/mcp/index.ts

// Antes del loop MCP_TOKENS
if (env.MAINTENANCE_AGENT_TOKEN && token === env.MAINTENANCE_AGENT_TOKEN) {
  return { ok: true, user: 'maintenance-agent' };
}

El check es add-only: no modifica ni reemplaza la lógica existente de MCP_TOKENS. El orden de evaluación es:

1. MAINTENANCE_AGENT_TOKEN (check dedicado, nuevo).
2. Loop MCP_TOKENS (lógica preexistente, sin cambios).

Identidad resultante

El usuario se mapea como maintenance-agent (string literal), lo que permite distinguir su actividad en activity_log del resto de usuarios/agentes.

Tipo en functions/types.ts

export interface Env {
  // ...campos existentes...
  MAINTENANCE_AGENT_TOKEN?: string;  // ← añadido
}

Campo opcional (?) — si la variable no está configurada, el check falla silenciosamente y el flujo continúa hacia MCP_TOKENS.

Configuración en infraestructura

El token se gestiona como Secret en Cloudflare Pages (entorno del workspace), independiente de MCP_TOKENS. Esto permite:

• Rotarlo sin afectar a los tokens de miembros del equipo.
• Revocarlo de forma aislada si el routine se comporta mal.

Próximos pasos documentados

Actualizar el prompt del routine Maintenance-Weekly para que realice un curl directo al endpoint /api/mcp con el Bearer, invocando send_maintenance_email vía JSON-RPC tools/call, en lugar de depender del connector interactivo de claude.ai.

Seguridad

Véase también

• [[workspace—que-es-workspace]]
• [[workspace—agentes-ia]]