Hatchet MCP

hatchet-mcp

Un servidor MCP que permite a los agentes de IA observar y operar flujos de trabajo de Hatchet: estado, ejecuciones, registros, workers y métricas, además de activar / cancelar / reproducir.

Por qué: Hatchet tiene una gran API pero no tiene MCP. Esto la envuelve para que los agentes (Claude Code / Desktop, etc.) puedan ver y actuar sobre el estado de los flujos de trabajo.

Instalación

Agrega esto a tu configuración de MCP en Claude Code / Claude Desktop:

{
  "mcpServers": {
    "hatchet": {
      "command": "npx",
      "args": ["-y", "hatchet-mcp"],
      "env": { "HATCHET_CLIENT_TOKEN": "<your-hatchet-api-token>" }
    }
  }
}

Obtén el token desde el panel de Hatchet → API tokens. El token es un JWT que codifica la URL del servidor y el tenant, por lo que es la única configuración requerida.

Configuración

Variable	Requerida	Descripción
HATCHET_CLIENT_TOKEN	Sí	Token de API de Hatchet (JWT). Codifica la URL del servidor + el tenant, por lo que normalmente es todo lo que necesitas.
HATCHET_API_BASE	No	Sobrescribe la URL base de la API. Quienes usen auto-hospedaje pueden apuntar a cualquier instancia de Hatchet.
HATCHET_TENANT_ID	No	Sobrescribe el ID de tenant decodificado del token.

¿Auto-hospedaje? Configura HATCHET_API_BASE con tu propia instancia de Hatchet y funcionará en cualquier lugar.

Herramientas

Observabilidad (solo lectura)

Herramienta	Descripción
whoami	Muestra el tenant y la URL del servidor de Hatchet resueltos y confirma que el token funciona.
list_workflows	Lista las definiciones de flujos de trabajo del tenant.
list_runs	Lista las ejecuciones de flujos de trabajo (con una ventana de retroceso opcional y filtros).
get_run	Obtiene el detalle completo de una ejecución de flujo de trabajo: estado, tareas, errores.
get_run_logs	Obtiene las líneas de registro de una tarea por su ID externo.
list_workers	Lista los workers y su estado.
get_queue_metrics	Obtiene métricas de tareas/colas del tenant (salud de la cola).

Acciones (mutan el estado en vivo)

Herramienta	Descripción
trigger_workflow	Activa una nueva ejecución de flujo de trabajo por nombre con una carga útil JSON de entrada.
cancel_runs	Cancela una o más ejecuciones/tareas por ID externo.
replay_runs	Reproduce/reintenta una o más ejecuciones/tareas por ID externo.

Seguridad

Las herramientas de lectura (whoami, list_workflows, list_runs, get_run, get_run_logs, list_workers, get_queue_metrics) no son destructivas.

trigger_workflow, cancel_runs y replay_runs mutan el estado en vivo: sus descripciones están prefijadas con MUTATES LIVE STATE para que los agentes y usuarios sepan que afectan ejecuciones reales.

El token otorga acceso completo al tenant: trátalo como un secreto. Nunca lo confirmes en el control de versiones.

Desarrollo

pnpm install
pnpm test    # vitest
pnpm build   # tsup -> dist/index.js

TypeScript / ESM, probado con vitest.

Estado

v0.1.0: todas las herramientas verificadas contra Hatchet Cloud; funciona con instancias auto-hospedadas mediante HATCHET_API_BASE. trigger_workflow usa el endpoint estable /workflow-runs/trigger.