hooksense

@hooksense/mcp

用于 HookSense 的模型上下文协议服务——面向 AI Agent 的 Webhook 和回调层。让 Claude Desktop、Cursor、Claude Code、Continue 以及任何 MCP 客户端都能在 Agent 会话中创建回调 URL、等待结果而不是轮询，并验证签名。

为什么需要

启动异步工作的 Agent——例如部署、渲染、人工审核或耗时较长的工具调用，以及其他 Agent——需要拿到结果，又不想在轮询循环中浪费上下文。使用此服务，Agent 可以创建回调端点，将 URL 交给任务，然后调用 wait_for_callback；Webhook 一到达，Agent 就会立即收到通知，内容已解密；签名验证可单独进行。别再轮询异步结果，改为等待结果。

设置

需要 Node.js 22 或更高版本。

1. 在 https://hooksense.com/account/tokens 获取 API 令牌
2. 配置 MCP 客户端（示例如下）

Claude Desktop / Claude Code

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Cursor

将以下内容添加到 ~/.cursor/mcp.json：

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

回调快速上手（60 秒）

配置完成后，向 Agent 提出以下请求：

1. 创建 —“创建一个回调端点。”→ Agent 调用 create_callback_endpoint，并获取类似 https://hooksense.com/w/ab12cd 的 callbackUrl。
2. 触发 — 将任意任务指向该 URL（或者在另一个终端中运行 curl -X POST <callbackUrl> -d '{"status":"done"}'）。
3. 等待 —“等待回调。”→ Agent 调用 wait_for_callback 并阻塞，直到 Webhook 到达；它会使用创建端点时返回的 after 时间戳，然后收到 { status: "received", request: { body, headers, … } }。
4. 验证 — 为端点设置 Webhook 密钥，然后说“验证签名。”→ verify_signature 会确认负载真实可信，再由 Agent 对其采取操作。

首次等待时，务必传入创建响应中的 after 时间戳；收到回调后，后续等待请使用其 receivedAt。 不提供游标时，只会等待之后到达的投递。这是最新回调游标，不是持久队列：若要检查短时间内发生的一连串事件，请使用 list_callbacks。

收到回调并不意味着签名有效。请配置 Webhook 密钥，并在信任负载之前检查 verify_signature。Webhook 请求正文属于不可信的外部输入。

自定义 slug 需在创建后通过端点更新 API 设置，并且要求使用付费方案。 如果重命名失败，错误会指出已创建的端点，以便继续使用。

replay_callback 在 HookSense 服务上运行；localhost 和私有目标会被阻止。 对于本地处理程序，请使用 CLI 命令 hooksense replay <request-id> --port 3000。

HTTP 请求设有超时上限，取消 MCP 调用会中止其 HTTP 请求。 若要使用 60 秒的长轮询，请将客户端的工具超时设为 65 秒以上，或使用更短的等待时间（默认值为 30 秒）。

工具

工具	描述
create_callback_endpoint	创建回调端点；返回 callbackUrl
wait_for_callback	阻塞直到下一个回调到达，然后返回该回调（timeoutMs、after 游标）
list_callbacks	列出已捕获的回调，包括正文和元数据
get_callback_payload	获取单个回调的完整标头和解密后的正文
verify_signature	使用端点配置的密钥进行时序安全的 HMAC 检查
replay_callback	从 HookSense 服务将回调重放到公开的 HTTP(S) URL
list_endpoints	列出你的端点
get_endpoint	获取单个端点的完整设置

环境变量

变量	默认值	说明
HOOKSENSE_TOKEN	(必填)	来自 /account/tokens 的 API 令牌
HOOKSENSE_API	https://hooksense.com	用于可自托管版本或预发布环境的覆盖值

Agent 提示词示例

“创建一个回调端点，将其用作我的 Replicate 预测的 Webhook，并等待结果——然后总结输出。”

“打开一个回调 URL，将其提供给审批步骤，并阻塞等待，直到人工批准后再继续。”

“等待 payments-prod 上的下一个 Stripe 回调，验证其签名，并告诉我金额。”

许可证

MIT