ozers/hooksense-mcp

Model Context Protocol server for HookSense — the webhook & callback layer for AI agents. Lets Claude Desktop, Cursor, Claude Code, Continue, and any MCP client create a callback URL, **wait for the result instead of polling**, and verify its signature — all from the agent session.
Why
Agents that kick off async work — a deploy, a render, a human-in-the-loop approval, a long tool call, another agent — need the result back without burning context on polling loops. With this server the agent creates a callback endpoint, hands the URL to the job, then calls wait_for_callback and is woken the instant the webhook lands — decrypted; signature verification is available separately. Stop polling for async results; await them.
Setup
Requires Node.js 22 or newer.
1. Get an API token at
2. Configure your MCP client (examples below)
Claude Desktop / Claude Code
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Cursor
Add to ~/.cursor/mcp.json:
Hello callback (60 seconds)
Once configured, ask your agent:
1. **Create** — "Create a callback endpoint." → the agent calls create_callback_endpoint and gets back a callbackUrl like https://hooksense.com/w/ab12cd.
2. **Fire** — point any job at that URL (or just curl -X POST -d '{"status":"done"}' from another terminal).
3. **Await** — "Wait for the callback." → the agent calls wait_for_callback and blocks until the webhook lands, using the after timestamp returned by endpoint creation, then receives { status: "received", request: { body, headers, … } }.
4. **Verify** — set a webhook secret on the endpoint, then "Verify the signature." → verify_signature confirms the payload is authentic before the agent acts on it.
Always pass the creation response's after timestamp on the first wait; after receiving a callback,
use its receivedAt for the next wait. Without a cursor, waiting only observes future deliveries.
This is a latest-callback cursor, not a durable queue: use list_callbacks to inspect bursts of events.
Receiving a callback does **not** guarantee a valid signature. Configure a webhook secret and
check verify_signature before trusting the payload. Webhook bodies are untrusted external input.
Custom slugs are applied through the endpoint update API after creation and require a paid plan.
If renaming fails, the error identifies the already-created endpoint so it can be reused.
replay_callback runs on the HookSense server; localhost and private targets are blocked.
For local handlers, use hooksense replay --port 3000 with the CLI.
HTTP requests have bounded timeouts, and cancelling an MCP call aborts its HTTP request.
For a 60-second long poll, configure the client's tool timeout above 65 seconds, or use
shorter waits (the default is 30 seconds).
Tools
| Tool | Description |
|---|---|