hooksense-mcp is the Model Context Protocol (MCP) server for HookSense, positioned as a webhook and callback layer for AI agents. It enables Claude Desktop, Cursor, Claude Code, Continue, and any MCP client to create callback URLs, wait for results instead of polling, and verify signatures within an agent session.
Purpose When an agent initiates asynchronous work (such as a deployment, a render, human-in-the-loop approval, a long-running tool call, or another agent), it needs to get the result back without consuming context on a polling loop. With this server, the agent can create a callback endpoint, hand the URL to the task, then call wait_for_callback to be woken the moment the webhook arrives; signature verification can be done separately. The goal is to stop polling for asynchronous results and instead wait for them.
Key capabilities
- Create a callback endpoint: the agent calls create_callback_endpoint and gets a callbackUrl like https://hooksense.com/w/ab12cd .
- Wait for a callback: the agent calls wait_for_callback, which blocks until the webhook arrives, using the after timestamp returned when the endpoint was created, then receives { status: "received", request: { body, headers, … } }.
- Verify signatures: after setting a webhook secret on the endpoint, call verify_signature to confirm the payload is authentic before letting the agent act on it.
- List callbacks: use list_callbacks to inspect bursts of events.
- Replay callbacks: replay_callback runs on the HookSense server and blocks localhost and private targets; for local handlers you can use the CLI command hooksense replay <request-id> --port 3000.
How to use Requires Node.js 22 or later. First get an API token at https://hooksense.com/account/tokens , then configure the MCP client.
Claude Desktop / Claude Code: add the configuration in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Cursor: add it to ~/.cursor/mcp.json.
Once configured, you can use it with the following flow:
- Create: tell the agent "Create a callback endpoint." The agent calls create_callback_endpoint and returns a callbackUrl.
- Trigger: point any task at that URL, or run curl -X POST <callbackUrl> -d '{"status":"done"}' in another terminal.
- Wait: tell the agent "Wait for the callback." The agent calls wait_for_callback and blocks until the webhook arrives, using the after timestamp returned when the endpoint was created, then receives { status: "received", request: { body, headers, … } }.
- Verify: set a webhook secret on the endpoint, then say "Verify the signature." verify_signature confirms the payload is authentic before the agent acts.
Example agent prompts:
- "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.”
Use cases Suitable for agent workflows that need asynchronous result delivery, including deployments, rendering, human-in-the-loop approvals, long-running tool calls, another agent, and more. Also suitable for scenarios that need to wait for callbacks from external services such as Stripe and verify signatures.
Limitations and notes
- On the first wait, always pass the after timestamp from the creation response; after receiving a callback, use its receivedAt for the next wait. Without a cursor, a wait can only observe future deliveries. This is a latest-callback cursor, not a durable queue; use list_callbacks to check for bursts of events.
- Receiving a callback does not guarantee a valid signature. You should configure a webhook secret and check verify_signature before trusting the payload. The webhook body is untrusted external input.
- A custom slug is applied after creation via the endpoint update API and requires a paid plan. If renaming fails, the error identifies the endpoint that was created so it can be reused.
- replay_callback runs on the HookSense server and blocks localhost and private targets. For local handlers, use the CLI command hooksense replay <request-id> --port 3000.
- HTTP requests have a timeout limit, and canceling an MCP call aborts its HTTP request. For a 60-second long poll, configure the client's tool timeout to 65 seconds or more, or use a shorter wait (default 30 seconds).
