Hooklistener
MCP integration

Debug webhooks from
your AI coding agent

Hooklistener is a webhook debugger with a hosted MCP server. It gives Claude Code, Codex, Cursor, and any MCP client 67 tools to create webhook URLs, wait for the next webhook, verify its signature, replay it to localhost, and test emails and WebSocket clients — without leaving the conversation.

Updated September 2026 · Streamable HTTP · OAuth · No local install

Start freeSetup guide
AI assistant
> Create a debug endpoint called 'Stripe Webhooks'
I'll create that endpoint for you.
create_endpoint({ name: "Stripe Webhooks" })
→ https://hook.hooklistener.com/e/abc123
> Trigger a test payment and verify the webhook fires
Triggering it now, then waiting for the webhook.
wait_for_request({ endpoint_id: "abc123", timeout: 60 })
→ POST /webhook • received after 3.1s • stripe-signature: ...
▊

67 tools your AI agent can use

One hosted server covers webhooks, email inboxes, WebSocket and MQTT endpoints, localhost tunnels, and uptime monitors. Your agent picks the right tool when you ask it to test, verify, or replay something.

Tools come in seven toolsets. A new workspace lists 26: every webhook tool plus the tool that starts each other product. Create your first inbox, monitor or real-time endpoint and that toolset appears the next time your client connects. To list everything up front, send the header x-hooklistener-toolsets: all.

See the changelog for what landed recently, or every input and output in the MCP tool reference.

Webhooks

Capture, inspect, verify and replay webhook requests

create_endpoint

Create a debug endpoint and get a unique webhook URL to paste into Stripe, GitHub, Shopify, or your own service.

wait_for_request

Wait for a matching webhook (method, path, event type, header or body match) as a durable task, or hold the call open up to 60 s with blocking: true.

list_requests

List captured webhooks, or search them across the organization by text, event type, status or time.

verify_request_signature

Check Stripe, GitHub, or Slack signatures against a stored secret and report timestamp freshness at capture time.

replay_request

Replay or forward a webhook to any URL or your local CLI tunnel, with an edited body and optional Stripe, GitHub, or Slack re-signing.

diagnose_request

A health verdict for one request covering the response, body, mock rules, and every forwarding attempt — with next steps.

Also: list_endpoints, get_endpoint, update_endpoint, delete_endpoint, get_request, delete_request, investigate_request_retries, validate_request, diff_requests, compare_requests, list_request_forwards, list_secrets, create_secret, delete_secret, cancel_task

Rules, threads and alerts

Mock responses, correlated threads and integration alerts

create_response_rule

Return a different status, headers, or body when a request matches conditions — simulate failures and retries.

test_response_rules

Evaluate your ordered rules against a synthetic request without capturing any traffic.

set_thread_rule

Correlate requests by a field such as an order or payment ID and follow each object's lifecycle.

list_endpoint_anomalies

See what changed in an integration: new event types, missing fields, type changes, volume drops, or a sender that went silent.

Also: update_response_rule, delete_response_rule, list_request_threads, list_thread_requests, delete_thread_rule, set_endpoint_alerts

Replay cases and suites

Turn real webhooks into a regression suite

save_request_case

Save a captured request as a replayable case with a default target and assertions.

run_endpoint_cases

Replay one case or a whole suite against localhost, staging, or production.

wait_for_case_run

Wait for the run to finish and read a pass/fail report per case.

Also: list_endpoint_cases, update_request_case, delete_request_case, replay_request_case, list_endpoint_case_suites, create_endpoint_case_suite, update_case_suite, delete_case_suite, add_case_to_suite, remove_case_from_suite, list_endpoint_case_runs, get_case_run

Real-time: WebSocket, Socket.IO, MQTT, SSE

Hosted servers your agent can connect clients to and drive

create_realtime_endpoint

Create a hosted WebSocket, Socket.IO, MQTT-over-WebSocket, or SSE endpoint for your client to connect to.

wait_for_realtime_message

Wait until your client sends (or receives) a message that contains the text you expect.

send_realtime_message

Push a message, event, or MQTT topic to one session or broadcast to all.

manage_realtime_rules

Create auto-responder rules so the endpoint answers your client like a real server.

Also: list_realtime_endpoints, list_realtime_sessions, get_realtime_messages

Email inboxes

Test signup, magic-link, and OTP emails end to end

create_inbox

Create a disposable inbox and get a generated address.

wait_for_email

Wait for the email to arrive — verify signup and password reset flows without polling.

get_email

Read the subject, sender, headers, and bodies to pull out links and codes.

Also: list_inboxes, list_emails

Uptime monitors

Watch the API that receives your webhooks

create_monitor

Start monitoring a URL's availability.

get_monitor_status

Uptime percentage, average response time, and recent checks.

Also: list_monitors, update_monitor, delete_monitor

Localhost tunnels

Inspect and replay traffic captured by the CLI tunnel

plan_tunnel_action

Plan a tunnel action and see its risk and required confirmation before anything changes.

replay_tunnel_capture

Replay a captured request through your local tunnel after explicit confirmation.

Also: read_tunnel_capture_sensitive, add_tunnel_case_capture

Real use cases

How developers use the MCP server to run end-to-end webhook tests, verify email flows, fix signature bugs, and test real-time clients — all from their AI coding agent.

Let your agent verify webhooks end to end

Agentic testing without polling loops: your AI triggers an action in your app, then calls wait_for_request, which waits for the matching webhook as a durable task (or holds the call open up to 60 seconds with blocking: true). The test passes or fails in a single conversation, and you see the actual payload your code sent.

  • wait_for_request waits for the webhook as a task that survives timeouts
  • Match on method, path, event type, headers, or body fields
  • Verify the payload your code actually sent, not what you assumed
  • No sleep-and-retry scripts or manual dashboard refreshing
AI assistant
> Create a test order and verify the webhook fires
Creating the order, then waiting for the webhook.
wait_for_request({ endpoint_id: "ep_123", timeout: 60 })
→ POST /webhook • received after 3.4s
→ { "event": "order.created", "id": "ord_42" }
Webhook verified — the payload matches the new order.

Test a signup email flow end to end

Need to prove your app actually sends the welcome email? Ask your AI to create an email inbox, sign up with the generated address, and wait for the message with wait_for_email. The free plan includes one inbox.

  • create_inbox returns a generated email address instantly
  • wait_for_email waits for the message and returns it when it lands
  • Inspect subject, sender, and body with get_email
  • Works for signup, magic-link, OTP, and password reset flows
Walkthrough: test signup, magic-link and OTP emails with an AI agent
AI assistant
> Verify the welcome email goes out on signup
Creating a test inbox, then signing up with it.
create_inbox({ name: "Signup test" })
→ Inbox created • address generated
wait_for_email({ inbox_id: "inb_9f2", timeout: 60 })
→ Email received after 2.8s • "Welcome aboard!"

Ask why a webhook failed

When a request 500s, you don't have to piece together logs yourself. diagnose_request analyzes the captured response, body, mock rules, and every forwarding attempt, then returns a health verdict with findings and concrete suggestions.

  • Health verdict per request: ok, info, warning, or error
  • Findings cover response status, invalid JSON bodies, and missing headers
  • Forwarding and replay attempts are analyzed in the same report
  • investigate_request_retries explains duplicate deliveries
AI assistant
> Why did the last Stripe webhook fail?
diagnose_request({ endpoint_id: "ep_123", request_id: "req_a1b2" })
→ Health: error • response returned 500
→ Finding: forward to localhost:3000 timed out
→ Suggestion: start the dev server and replay

Verify a Stripe signature, then replay it to localhost

Signature bugs are the classic webhook failure. Your agent checks the captured request against your stored signing secret, then replays it to your local server re-signed with a fresh timestamp — so your handler sees exactly what Stripe would send.

  • verify_request_signature supports Stripe, GitHub, and Slack
  • Reports whether the timestamp was fresh at capture time
  • replay_request can edit the body and re-sign before sending
  • Save it as a case and rerun the suite after every fix
AI assistant
> Why is my handler rejecting the Stripe webhook?
verify_request_signature({ provider: "stripe", ... })
→ Signature valid • your handler reads the parsed body
replay_request({ target_url: "http://localhost:3000/webhooks" })
→ 200 OK after the raw-body fix • re-signed

Test a WebSocket or MQTT client

Point your client at a hosted WebSocket, Socket.IO, MQTT, or SSE endpoint. Your agent waits for the message your client should send, answers like your real server, and reads the whole session back.

  • create_realtime_endpoint picks the protocol
  • wait_for_realtime_message waits for the text you expect
  • send_realtime_message pushes events or MQTT topics
  • Auto-responder rules simulate your server's replies
Walkthrough: test WebSocket, Socket.IO, MQTT and SSE clients with an AI agent
AI assistant
> Check my app subscribes to the orders channel
create_realtime_endpoint({ name: "Orders", protocol: "websocket" })
→ wss://… ready • client connected
wait_for_realtime_message({ contains: "subscribe" })
→ {"op":"subscribe","channel":"orders"} after 0.4s

Set up in under a minute

Pick your AI tool, add one URL, and sign in with your browser. Nothing to install or run locally.

Terminal
claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp

# Then run /mcp inside Claude Code, pick "hooklistener",
# and sign in with your browser (OAuth). Tokens refresh automatically.

# --scope project shares it with your team (writes .mcp.json)
# --scope user enables it in all your projects

Prerequisites: A Hooklistener account (the free plan works). OAuth handles sign-in in any client that supports remote MCP auth, and you can grant read-only access for inspection. For clients without OAuth, create an API key in Organization Settings > API Keys.

Step-by-step guide for your client: Claude Code, Codex, Cursor, VS Code, Claude, ChatGPT, Gemini CLI, Windsurf, Zed, OpenCode, Grok.

For detailed setup instructions, see our step-by-step guide for AI coding assistants or the MCP setup docs.

Frequently asked questions about the MCP server

Everything you need to know about using the MCP server

What is the Hooklistener MCP server?
It is a hosted MCP (Model Context Protocol) server at https://app.hooklistener.com/api/mcp that gives AI coding agents 67 tools in 7 toolsets: webhooks (capture, inspect, verify, replay), rules and threads, replay suites, WebSocket/Socket.IO/MQTT/SSE endpoints, email inboxes, uptime monitors, and localhost tunnels. Nothing runs on your machine — you add one URL and sign in.
Why does my agent only see some of the tools?
To keep your agent's context small, a session lists only the toolsets your workspace uses. A new workspace sees 26 of the 67 tools: every webhook tool plus the tool that starts each other product (create_inbox, create_monitor, create_realtime_endpoint, save_request_case, create_response_rule). After your first inbox, monitor or real-time endpoint, that toolset appears when your client reconnects. To list everything, send the x-hooklistener-toolsets: all header (or a comma-separated list such as email,monitors). Hidden tools can still be called.
Which AI tools work with Hooklistener's MCP server?
Claude Code, Claude.ai and Claude Desktop (as a custom connector), OpenAI Codex, Cursor, VS Code with GitHub Copilot, Gemini CLI, Windsurf, and any other MCP client that supports the Streamable HTTP transport.
How can Claude Code or Codex receive a webhook?
Ask the agent to call create_endpoint to get a public webhook URL, point your provider (Stripe, GitHub, Shopify, or your own app) at it, then call wait_for_request. It waits for the matching webhook — as a durable task the agent follows, or as a call held open up to 60 seconds with blocking: true — so the agent can read the exact payload, verify its signature, and replay it to your local server — all in one conversation.
How do I authenticate?
With OAuth: add the server URL and your client opens a browser sign-in. Your client requests full access or read-only access (for example, codex mcp login hooklistener --scopes read_only), and the consent screen shows which one before you approve. Clients without OAuth support can send a Hooklistener API key (hklst_…) as a Bearer token instead.
Can I give my agent read-only access?
Yes. Request the read_only OAuth scope and the agent can search, wait for, diff, validate, and diagnose traffic, but cannot create, edit, delete, replay, forward, or send anything. Common credentials in headers, cookies, query strings, and JSON bodies are masked in every tool result.
Is the MCP server free?
Yes. MCP works on every plan, including free. The free plan includes 1 email inbox, 1 uptime monitor, and 3 saved replay cases. Stored signing secrets (used for signature checks and re-signed replays), Slack or webhook alerts, and AI request comparison need a paid plan.
Can my agent test WebSocket, MQTT, or SSE clients?
Yes. create_realtime_endpoint gives your client a hosted WebSocket, Socket.IO, MQTT-over-WebSocket, or SSE endpoint. The agent can wait for a specific message, send or broadcast messages, and set auto-responder rules so the endpoint behaves like your real server.
Is it safe to let an agent delete or replay things?
Deletes are two-step: the agent must preview with dry_run and then confirm. Replays and forwards require an idempotency key, so a retried call never sends a webhook twice. Your data is scoped to your organization, sent over HTTPS, and hosted in Europe.
What transport does the server use?
Streamable HTTP (JSON-RPC 2.0 over HTTPS), the standard transport for remote MCP servers. There is no local process or stdio bridge to install.

Have more questions about the MCP server?

Read the full MCP documentation

Ready to debug webhooks
from your AI assistant?

Connect your AI coding tool to Hooklistener in under a minute. 67 tools for webhooks, replay suites, email inboxes, real-time endpoints, tunnels, and uptime — all from the conversation.

Start freeView setup guide

Free tier available • No credit card required • Setup in under a minute • Read the docs