MCP Server

The HookSense MCP server is how an AI agent gets a callback layer. Over the Model Context Protocol — Claude Desktop, Cursor, Claude Code, Continue, and any MCP-compatible client — your agent mints a callback URL, hands it to a long-running tool, a human approver, or another agent, and awaits the signed result with wait_for_callback instead of polling. Run it with npx @hooksense/mcp.

The Tools

• create_callback_endpoint — mint a fresh callback URL to hand to an external system
• wait_for_callback — block until the result arrives, signature-verified and decrypted (no polling)
• get_callback_payload — read the full body and metadata of a captured callback
• verify_signature — confirm a callback's HMAC signature is authentic
• list_callbacks — summary of recent callbacks (method, status, provider, time)
• replay_callback — re-send a captured callback to any target URL (localhost, staging, prod)

Typical Pattern

1. Agent calls create_callback_endpoint and passes the URL to a long tool call, an approval step, or a downstream agent.
2. Agent calls wait_for_callback and the run pauses cleanly until the external system POSTs back.
3. When the callback lands, wait_for_callback returns it; verify_signature and get_callback_payload confirm and read it.

Use it for long tool calls, human-in-the-loop approvals, multi-agent hand-offs, and external async jobs.

Setup

1. Create an API token

Go to your account page → API tokens → Create token. Copy the hsk_... value — it's shown only once.

2. Configure your MCP client

Claude Desktop & Claude Code

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Edit ~/.cursor/mcp.json:

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

3. Restart your MCP client

The HookSense tools will appear in the tool palette. Your agent can now call them.

Example prompts

"Create a callback endpoint, kick off the export job with that URL, then wait for the callback and summarize the result."

"Replay the last 3 captured callbacks against http://localhost:3000/webhooks/stripe so I can test my handler refactor."

"Wait for the approval callback on /w/deploy-gate, verify its signature, then continue the deploy."

Security model

• API tokens are bearer credentials. Treat them like passwords. Revoke immediately if leaked.
• Tokens are stored as SHA-256 hashes on our side — we can't recover the plaintext, so you'll need to issue a new one if you lose yours.
• Bearer-authed requests bypass cookie-based CSRF protection (by design — they're immune to CSRF).
• Each token grants full account access. We recommend a separate token per machine/agent so revocation is granular.

Troubleshooting

"HOOKSENSE_TOKEN env var is required" — your client isn't passing the env var through. Check the JSON config above.

"Invalid or expired token (401)" — the token was revoked or mistyped. Generate a new one in /account.

Tool calls hang — the MCP server uses stdio. Make sure no other tools are writing to your client's stdin/stdout.

Source

The MCP server is open source. Read the code or file issues at github.com/ozers/hooksense.