hooksense

@hooksense/mcp

HookSense の Model Context Protocol サーバーです。AI エージェント向けの Webhook およびコールバックレイヤーです。Claude Desktop、Cursor、Claude Code、Continue、およびあらゆる MCP クライアントから、コールバック URL を作成し、ポーリングせずに結果を待機して、その署名を検証できます。すべてエージェントのセッションから行えます。

概要

デプロイ、レンダリング、Human-in-the-loop の承認、長時間のツール呼び出し、別のエージェントなど、非同期処理を開始するエージェントは、ポーリングループにコンテキストを消費せずに結果を受け取る必要があります。このサーバーを使うと、エージェントはコールバックエンドポイントを作成し、その URL をジョブに渡してから、wait_for_callback を呼び出します。Webhook が届くとすぐに処理が再開され、データは復号済みです。署名検証は別途利用できます。非同期処理の結果をポーリングするのはやめて、到着を待ちましょう。

セットアップ

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 秒）

設定が完了したら、エージェントに次のように依頼します。

1. 作成 — 「コールバックエンドポイントを作成して」と依頼します。→ エージェントが create_callback_endpoint を呼び出し、https://hooksense.com/w/ab12cd のような callbackUrl を取得します。
2. 送信 — 任意のジョブの送信先にその URL を指定します（または、別のターミナルから curl -X POST <callbackUrl> -d '{"status":"done"}' を実行します）。
3. 待機 — 「コールバックを待って」と依頼します。→ エージェントが wait_for_callback を呼び出し、エンドポイント作成時に返された after タイムスタンプを使って Webhook が届くまで待機し、その後 { status: "received", request: { body, headers, … } } を受け取ります。
4. 検証 — エンドポイントに Webhook シークレットを設定し、「署名を検証して」と依頼します。→ verify_signature がペイロードの正当性を確認してから、エージェントが処理します。

最初の待機では、必ず作成時のレスポンスに含まれる after タイムスタンプを渡してください。コールバックを受け取った後は、次の待機にその receivedAt を使います。カーソルを指定しない場合、待機によって監視されるのは今後の配信のみです。 これは最新のコールバックを基準にするカーソルであり、永続キューではありません。イベントが短時間に集中して届いた場合は、list_callbacks で確認してください。

コールバックを受信しても、署名が有効であるとは限りません。Webhook シークレットを設定し、ペイロードを信頼する前に verify_signature で確認してください。Webhook の本文は、信頼できない外部入力です。

カスタムスラッグは、エンドポイント作成後にエンドポイント更新 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	ヘッダー全体と復号済みの本文を含むコールバックを 1 件取得します
verify_signature	エンドポイントに設定されたシークレットに対してタイミングセーフな HMAC 検証を行います
replay_callback	HookSense サーバーから、公開 HTTP(S) URL にコールバックを再送信します
list_endpoints	エンドポイントを一覧表示します
get_endpoint	エンドポイント 1 件の設定全体を取得します

環境変数

変数	デフォルト	備考
HOOKSENSE_TOKEN	(必須)	/account/tokens で取得した API トークン
HOOKSENSE_API	https://hooksense.com	セルフホスト環境またはステージング環境での上書き用

エージェントプロンプトの例

「コールバックエンドポイントを作成し、Replicate の予測用 Webhook として設定して、結果が返るまで待ちます。その後、出力を要約してください。」

「コールバック URL を開いて承認ステップに渡し、人間が承認するまで処理をブロックしてから続行してください。」

「payments-prod の次の Stripe コールバックを待ち、署名を検証して、金額を教えてください。」

ライセンス

MIT