Hatchet MCP

hatchet-mcp

Um servidor MCP que permite que agentes de IA observem e operem workflows do Hatchet — status, execuções, logs, workers e métricas, além de acionar / cancelar / reproduzir.

Por quê: O Hatchet tem uma ótima API, mas não tem MCP. Este servidor a encapsula para que agentes (Claude Code / Desktop, etc.) possam ver e agir sobre o estado dos workflows.

Instalação

Adicione isto à sua configuração MCP do Claude Code / Claude Desktop:

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

Obtenha o token no painel do Hatchet → API tokens. O token é um JWT que codifica a URL do servidor e o tenant, então é a única configuração necessária.

Configuração

Variável	Obrigatória	Descrição
HATCHET_CLIENT_TOKEN	Sim	Token da API do Hatchet (JWT). Codifica a URL do servidor + tenant, então normalmente é tudo o que você precisa.
HATCHET_API_BASE	Não	Substitui a URL base da API. Quem faz self-hosting pode apontar para qualquer instância do Hatchet.
HATCHET_TENANT_ID	Não	Substitui o ID do tenant decodificado do token.

Faz self-hosting? Defina HATCHET_API_BASE para sua própria instância do Hatchet e funcionará em qualquer lugar.

Ferramentas

Observabilidade (somente leitura)

Ferramenta	Descrição
whoami	Mostra o tenant resolvido do Hatchet + URL do servidor e confirma que o token funciona.
list_workflows	Lista as definições de workflows do tenant.
list_runs	Lista execuções de workflows (com janela de retrospectiva opcional e filtros).
get_run	Obtém os detalhes completos de uma execução de workflow — status, tarefas, erros.
get_run_logs	Obtém linhas de log de uma tarefa pelo seu ID externo.
list_workers	Lista workers e seus status.
get_queue_metrics	Obtém métricas de tarefas/filas do tenant (saúde da fila).

Ações (alteram o estado ativo)

Ferramenta	Descrição
trigger_workflow	Aciona uma nova execução de workflow pelo nome com um payload JSON de entrada.
cancel_runs	Cancela uma ou mais execuções/tarefas pelo ID externo.
replay_runs	Reproduz/re-tenta uma ou mais execuções/tarefas pelo ID externo.

Segurança

As ferramentas de leitura (whoami, list_workflows, list_runs, get_run, get_run_logs, list_workers, get_queue_metrics) não são destrutivas.

trigger_workflow, cancel_runs e replay_runs alteram o estado ativo — suas descrições são prefixadas com MUTATES LIVE STATE para que agentes e usuários saibam que afetam execuções reais.

O token concede acesso total ao tenant — trate-o como um segredo. Nunca o envie para o controle de versão.

Desenvolvimento

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

TypeScript / ESM, testado com vitest.

Status

v0.1.0 — todas as ferramentas verificadas contra o Hatchet Cloud; funciona com instâncias self-hosted via HATCHET_API_BASE. trigger_workflow usa o endpoint estável /workflow-runs/trigger.