HookSense

@hooksense/mcp

Servidor Model Context Protocol para HookSense — a camada de webhook e callback para agentes de IA. Permite que Claude Desktop, Cursor, Claude Code, Continue e qualquer cliente MCP criem uma URL de callback, aguardem o resultado em vez de fazer polling e verifiquem sua assinatura — tudo a partir da sessão do agente.

Por quê

Agentes que iniciam trabalho assíncrono — um deploy, um render, uma aprovação humana no loop, uma chamada de ferramenta longa, outro agente — precisam do resultado de volta sem queimar contexto em loops de polling. Com este servidor, o agente cria um endpoint de callback, entrega a URL para o trabalho e então chama wait_for_callback e é acordado no instante em que o webhook chega — com assinatura verificada e descriptografado. Pare de fazer polling para resultados assíncronos; aguarde-os.

Configuração

1. Obtenha um token de API em https://hooksense.com/account/tokens
2. Configure seu cliente MCP (exemplos abaixo)

Claude Desktop / Claude Code

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hooksense": {
      "command": "npx",
      "args": ["-y", "@hooksense/mcp"],
      "env": {
        "HOOKSENSE_TOKEN": "hsk_your_token_here"
      }
    }
  }
}

Cursor

Adicione em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hooksense": {
      "command": "npx",
      "args": ["-y", "@hooksense/mcp"],
      "env": {
        "HOOKSENSE_TOKEN": "hsk_your_token_here"
      }
    }
  }
}

Olá, callback (60 segundos)

Depois de configurado, peça ao seu agente:

1. Criar — "Crie um endpoint de callback." → o agente chama create_callback_endpoint e recebe um callbackUrl como https://hooksense.com/w/ab12cd.
2. Disparar — "aponte qualquer trabalho para essa URL (ou apenas curl -X POST <callbackUrl> -d '{"status":"done"}' de outro terminal)."
3. Aguardar — "Aguarde o callback." → o agente chama wait_for_callback e bloqueia até o webhook chegar, então recebe { status: "received", request: { body, headers, … } }.
4. Verificar (opcional) — defina um segredo de webhook no endpoint, então "Verifique a assinatura." → verify_signature confirma que o payload é autêntico antes de o agente agir sobre ele.

Sem polling, sem dashboards, sem copiar e colar.

Ferramentas

Ferramenta	Descrição
create_callback_endpoint	Cria um endpoint de callback; retorna o callbackUrl
wait_for_callback	Bloqueia até o próximo callback chegar e o retorna (timeoutMs, after cursor)
list_callbacks	Lista callbacks recebidos por um endpoint (visão resumida)
get_callback_payload	Busca um callback com cabeçalhos completos + corpo descriptografado
verify_signature	Verificação HMAC segura contra o segredo configurado do endpoint
replay_callback	Envia um callback recebido para qualquer URL de destino via POST
list_endpoints	Lista seus endpoints
get_endpoint	Obtém as configurações completas de um endpoint

Ambiente

Variável	Padrão	Observações
HOOKSENSE_TOKEN	(obrigatório)	Token de API de /account/tokens
HOOKSENSE_API	https://hooksense.com	Substituição para self-hosted/staging

Exemplos de prompts para agentes

"Crie um endpoint de callback, use-o como webhook para minha previsão do Replicate e aguarde o resultado — depois resuma a saída."

"Abra uma URL de callback, entregue-a à etapa de aprovação e bloqueie até que um humano aprove antes de continuar."

"Aguarde o próximo callback do Stripe em payments-prod, verifique sua assinatura e me diga o valor."

Licença

MIT