hookray-mcp
Allows capturing and replaying GitHub webhook requests for testing handler implementations.
Supports testing Shopify webhook handlers by capturing and replaying webhook payloads.
Enables testing of Stripe webhook handlers by capturing real requests, inspecting headers (including stripe-signature), and replaying them to local endpoints.
Provides ability to test Twilio webhook handlers by capturing and replaying incoming requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hookray-mcp create a disposable webhook URL to test my Stripe handler"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hookray-mcp
Webhook testing for AI agents — capture, inspect, replay HTTP requests from Claude Code, Cursor, Claude Desktop, or any MCP-compatible client.
hookray-mcp is the Model Context Protocol server for HookRay. Drop it into your AI agent's config and the agent can spin up disposable webhook URLs, watch incoming requests live, and replay captured payloads against your local handler — without leaving the chat.
Why this exists
AI coding agents increasingly write webhook handlers (Stripe, GitHub, Shopify, Twilio, …). The agent loop today is:
Generate handler code
Manually test it by triggering a real event
Manually copy/paste the captured payload back to the agent
Agent fixes the bug
Repeat from step 2
With hookray-mcp installed, the agent does steps 2–4 itself:
You: "Build me a Stripe webhook handler at /api/stripe."
Agent: [writes code, then calls hookray-mcp tools]
→ create_webhook_inbox
→ wait_for_request (you trigger an event in Stripe)
→ inspect_request
→ replay_request to localhost:3000/api/stripe
→ "Returned 500. The bug is in the signature check at line 14."Related MCP server: Webhook Capture MCP
Install
# Anywhere npx works
npx -y hookray-mcp@latest
# Or globally
npm install -g hookray-mcpNode.js 20+ required.
Configure your AI client
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"hookray": {
"command": "npx",
"args": ["-y", "hookray-mcp@latest"]
}
}
}Claude Code
claude mcp add hookray -- npx -y hookray-mcp@latestCursor
Add to .cursor/mcp.json in your project (or the global Cursor MCP config):
{
"mcpServers": {
"hookray": {
"command": "npx",
"args": ["-y", "hookray-mcp@latest"]
}
}
}With a HookRay API key (for Pro features)
If you have a HookRay account and want persistent inboxes, pass HOOKRAY_API_KEY:
{
"mcpServers": {
"hookray": {
"command": "npx",
"args": ["-y", "hookray-mcp@latest"],
"env": {
"HOOKRAY_API_KEY": "hkr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}Get a key at hookray.com/app/settings/api-keys.
Tools
Tool | Description | Auth |
| Generate a fresh | Anonymous OK. |
| List recent requests captured by an inbox (with filters: method, since, search, limit). | Anonymous OK. |
| Get the full method + headers + body + query params of a single captured request. | Anonymous OK. |
| Block (up to 60 s) until a new request arrives. Critical for AI agent dev loops. | Anonymous OK. |
| Forward a captured request to any URL — including | Anonymous OK. |
Environment variables
Variable | Default | Notes |
|
| Override for self-hosting or local dev. |
| (unset) | Required for persistent inboxes. Get one at hookray.com/app/settings/api-keys. |
Example: Stripe webhook handler dev loop
> "Add a Stripe webhook handler at /api/stripe/webhook in this Next.js app."
[agent writes app/api/stripe/webhook/route.ts]
> "Now test it."
[agent calls hookray-mcp]
→ create_webhook_inbox → https://hookray.com/api/hook/abc12345
→ "Paste this URL into Stripe → Add endpoint, then trigger an event."
[you trigger a test event from Stripe dashboard]
→ wait_for_request(inbox_id) → {method: POST, content_type: application/json, ...}
→ inspect_request(...) → full headers (incl. stripe-signature) + body
→ replay_request(destination_url=http://localhost:3000/api/stripe/webhook)
→ {status_code: 400, body: "No signatures..."}
→ "Your handler is reading req.json() before constructEvent. Switch to
req.text() — Stripe's signature check needs the raw body."
[agent edits the handler]
→ replay_request(...) → {status_code: 200}Free vs Pro
Capability | Free | HookRay Pro |
Anonymous inboxes | ✅ | ✅ |
Capture, list, inspect, wait | ✅ | ✅ |
Replay to any URL (incl. localhost) | ✅ | ✅ |
Inbox lifetime | 7 days | 10 years |
Multiple inboxes | 1 active | up to 10 |
Request history | 100 / month | 10,000 / month |
Pro is $9 / month at hookray.com/pricing.
Limitations & non-goals
stdio transport only for v0.1. SSE / HTTP transports may come later.
No automatic agent triggering of real Stripe events — you still need to fire the event yourself from the provider dashboard or CLI. (Provider-specific sample-payload tools are on the roadmap.)
No WebSocket realtime —
wait_for_requestlong-polls (1 s tick, 60 s max). Good enough for dev loops; not designed for production traffic.SSRF safety on
replay_requestis your responsibility (the package runs on your machine, in your network).
Roadmap
Provider-specific template tools (
send_stripe_test_event,send_github_test_event, …)SSE transport for hosted MCP gateways
Streamed responses for long-running replays
First-class self-host docs (point at your own HookRay instance via
HOOKRAY_BASE_URL)
Development
git clone https://github.com/ShotaTanikawa/hookray-mcp.git
cd hookray-mcp
pnpm install
pnpm build
pnpm testLicense
MIT © 2026 Shota Tanikawa. See LICENSE.
Made by @ShotaTanikawa · HookRay · Feedback welcome — open an issue.
Available Tools
5 toolscreate_webhook_inboxA
Create a new HookRay webhook inbox and return its public capture URL.
Inputs: persistent. Returns: inbox_id, url, expires_at, max_requests
inspect_requestB
Inspect the full headers, body, query params, and metadata for a captured request.
Inputs: inbox_id (required), request_id (required). Returns: method, headers, body, query_params, +3 more
list_requestsB
List webhook requests captured by a HookRay inbox.
Inputs: inbox_id (required), limit, method, since, +1 more. Returns: requests
replay_requestB
Replay a captured HookRay request to any destination reachable from this machine.
Inputs: inbox_id (required), request_id (required), destination_url (required), override_method, +1 more. Returns: status_code, response_body_preview, response_headers, latency_ms
wait_for_requestB
Block until a new webhook arrives at an inbox, or return a timeout result.
Inputs: inbox_id (required), timeout_seconds, since.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: creating an inbox, listing requests, inspecting a request, replaying a request, and waiting for new requests. No ambiguity between them.
All tools follow a consistent verb_noun pattern (e.g., create_webhook_inbox, list_requests). No mixing of conventions.
With 5 tools, the set is well-scoped for a webhook debugging server. Not too few or too many.
Core operations are covered (create, list, inspect, replay, wait). Missing delete functionality for inboxes or requests, but the agent can work around this minor gap.
Maintenance
Related MCP Connectors
Webhook, email, WebSocket and tunnel testing for AI agents: capture, wait, verify, replay.
Debug webhooks from your AI agent: inspect and replay captured webhooks on localhost.
Webhook URLs for AI agents: receive, wait for, replay, sign and verify webhooks (Stripe, GitHub…).
A webhook inbox for agents: one call returns a live URL. Mock, verify, inspect and replay.
Related MCP Servers
AlicenseAqualityDmaintenanceEnables AI coding agents to create webhook bins, inspect and replay HTTP requests, and stand up mock API endpoints directly from the editor.137 npmMIT- AlicenseAqualityCmaintenanceCaptures incoming webhook/HTTP requests and lets AI assistants inspect, wait for, and replay them to debug webhook integrations.6MIT
- AlicenseNot gradedqualityDmaintenanceEnables coding agents to receive and inspect real webhook payloads locally, send signature-valid test events for seven providers, and replay deliveries — all without leaving the machine.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create webhook URLs, wait for incoming deliveries, inspect payloads, and replay or send signed webhook events to a local handler.49 npmMIT