hooksense-mcp 是 HookSense 的 Model Context Protocol（MCP）服务器，定位为面向 AI 智能体的 Webhook 与回调层。它让 Claude Desktop、Cursor、Claude Code、Continue 以及任何 MCP 客户端能够在智能体会话中创建回调 URL、等待结果而不是轮询，并验证签名。
用途 当智能体发起异步工作（例如部署、渲染、人工参与审批、长时间工具调用或另一个智能体）时，需要在不消耗上下文进行轮询循环的情况下拿回结果。使用该服务器，智能体可以创建回调端点，把 URL 交给任务，然后调用 wait_for_callback，在 Webhook 到达的瞬间被唤醒；签名验证可单独进行。其目标是停止轮询异步结果，改为等待结果。
主要能力
- 创建回调端点：智能体调用 create_callback_endpoint，获得类似 https://hooksense.com/w/ab12cd 的 callbackUrl。
- 等待回调：智能体调用 wait_for_callback，阻塞直到 Webhook 到达，使用端点创建时返回的 after 时间戳，然后收到 { status: "received", request: { body, headers, … } }。
- 验证签名：在端点上设置 Webhook 密钥后，调用 verify_signature 确认载荷真实性，再让智能体据此行动。
- 列出回调：使用 list_callbacks 检查突发的事件。
- 重放回调：replay_callback 在 HookSense 服务器上运行，会阻止 localhost 和私有目标；本地处理器可使用 CLI 命令 hooksense replay <request-id> --port 3000。
使用方式 需要 Node.js 22 或更高版本。先在 https://hooksense.com/account/tokens 获取 API 令牌，然后配置 MCP 客户端。
Claude Desktop / Claude Code：在 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json 中添加配置。
Cursor：添加到 ~/.cursor/mcp.json。
配置完成后，可以按以下流程使用：
- 创建：对智能体说“Create a callback endpoint.”，智能体调用 create_callback_endpoint 并返回 callbackUrl。
- 触发：让任意任务指向该 URL，或在另一个终端执行 curl -X POST <callbackUrl> -d '{"status":"done"}'。
- 等待：对智能体说“Wait for the callback.”，智能体调用 wait_for_callback 并阻塞直到 Webhook 到达，使用端点创建时返回的 after 时间戳，然后收到 { status: "received", request: { body, headers, … } }。
- 验证：在端点上设置 Webhook 密钥，然后说“Verify the signature.”，verify_signature 会在智能体行动前确认载荷真实性。
示例智能体提示词：
- “Create a callback endpoint, use it as the webhook for my Replicate prediction, and wait for the result — then summarize the output.”
- “Open a callback URL, give it to the approval step, and block until a human approves before continuing.”
- “Wait for the next Stripe callback on payments-prod, verify its signature, and tell me the amount.”
适用场景 适合需要异步结果回传的智能体工作流，包括部署、渲染、人工参与审批、长时间工具调用、另一个智能体等。也适合需要等待 Stripe 等外部服务回调并验证签名的场景。
限制与注意事项
- 首次等待时始终传入创建响应中的 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 秒）。
