Available Tools
The Hooklistener MCP server exposes 73 tools, grouped into seven toolsets.
Toolsets
To keep your assistant's context small, each session lists only the toolsets your organization uses:
| Toolset | Listed when |
|---|---|
webhooks | Always |
rules | Your organization has a mock response rule, request-thread rule, or endpoint alert |
cases | Your organization has a saved replay case |
realtime | Your organization has a real-time endpoint |
email | Your organization has an email inbox |
monitors | Your organization has an uptime monitor |
tunnels | Your organization has an active tunnel investigation case |
Each toolset's entry tool (create_response_rule, save_request_case, create_realtime_endpoint, create_inbox, create_monitor) is always listed, so your assistant can start using any product. After it creates the first resource of that kind, reconnect the MCP client to list the rest of that toolset.
To choose toolsets yourself, send the x-hooklistener-toolsets header with a comma-separated list (for example email,monitors) or all. webhooks is always included. See Setup.
Toolsets only change which tools are listed. Every tool stays callable within your grant's scope.
Webhooks
Listed in every session.
Debug endpoints
| Tool | Description |
|---|---|
list_endpoints | List debug endpoints in the current organization |
get_endpoint | Get endpoint details and webhook URL |
create_endpoint | Create a debug endpoint |
update_endpoint | Update endpoint name, status, or default response |
delete_endpoint | Preview or permanently delete an endpoint |
Captured requests
| Tool | Description |
|---|---|
list_requests | List captured requests for an endpoint, or search across the organization with fuzzy text and event, status, or time filters |
get_request | Get full request details, including headers and body |
wait_for_request | Wait for a matching request, check existing traffic, or resume from a cursor |
delete_request | Preview or permanently delete a captured request |
diagnose_request | Summarize response, forwarding, body, and mock-rule issues for a request |
investigate_request_retries | Correlate repeated deliveries and compare their payloads, timing, and outcomes |
verify_request_signature | Verify a Stripe, GitHub, or Slack signature with a stored secret |
validate_request | Validate a captured JSON body against a JSON Schema |
diff_requests | Deterministically compare two requests, including across endpoints |
compare_requests | Compare 2–5 requests with AI-assisted analysis |
replay_request | Preview and replay a request, optionally edited or re-signed, to a URL or active CLI listener |
list_request_forwards | Page through forward and replay receipts for a request |
Secrets, async tasks and feedback
Secrets are encrypted organization-scoped values that tools can reference, for example to verify or re-sign webhooks.
| Tool | Description |
|---|---|
list_secrets | List secret names and metadata; values are never returned |
create_secret | Create an encrypted secret |
delete_secret | Preview or permanently delete a secret |
cancel_task | Stop a queued or running asynchronous task |
submit_feedback | Send feedback about Hooklistener to its developers, after asking you. Works with every access level. |
Rules
Conditional mock responses, request threads, and alerts.
| Tool | Description |
|---|---|
create_response_rule | Create or preview a conditional response rule (always listed) |
update_response_rule | Update, enable, disable, or preview a response rule |
delete_response_rule | Preview or permanently delete a response rule |
test_response_rules | Evaluate an endpoint's rules against a synthetic request |
list_request_threads | List correlation threads for an endpoint |
list_thread_requests | List the requests in one thread |
set_thread_rule | Create or update an endpoint's thread correlation rule |
delete_thread_rule | Preview or delete a thread rule |
set_endpoint_alerts | Turn request alerts on or off for an endpoint |
list_endpoint_anomalies | List anomalies detected in an endpoint's traffic |
Cases
Replay cases save captured requests as repeatable integration tests with optional response assertions.
| Tool | Description |
|---|---|
save_request_case | Save a captured request as a replay case (always listed) |
list_endpoint_cases | List saved cases for an endpoint |
update_request_case | Update case metadata, replay overrides, or assertions |
delete_request_case | Preview or permanently delete a saved case |
replay_request_case | Replay one saved case |
list_endpoint_case_suites | List named suites for an endpoint |
create_endpoint_case_suite | Create a named case suite |
update_case_suite | Update a suite name or description |
delete_case_suite | Preview or permanently delete a suite |
add_case_to_suite | Add a saved case to a suite |
remove_case_from_suite | Remove a saved case from a suite |
run_endpoint_cases | Run all endpoint cases, or one suite |
list_endpoint_case_runs | List case run reports for an endpoint |
get_case_run | Get a case run report |
wait_for_case_run | Wait for a case run to complete |
Common replay case fields:
| Field | Used by | Description |
|---|---|---|
endpoint_id | List/save/run tools | Debug endpoint ID |
request_id | save_request_case | Captured request ID to save |
case_id | Case replay/update/delete tools | Saved request case ID |
case_suite_id | Suite run/report tools | Optional suite ID |
target_url | Replay/run tools | Destination URL |
target_id | Replay/run tools | Saved endpoint replay target ID |
target | Replay/run tools | Set to cli to use an active CLI listener |
target_name | run_endpoint_cases | Optional name to save for a custom URL |
expected_status_code | Save/update tools | Response status assertion |
expected_json_body_subset_json | Save/update tools | JSON object expected in the replay response body |
wait | run_endpoint_cases | Wait for queued forwards and return aggregate results |
timeout_ms | Run/wait tools | Maximum wait time, capped at 120 seconds |
Realtime
WebSocket, Socket.IO, MQTT-over-WebSocket, and SSE debugging.
| Tool | Description |
|---|---|
create_realtime_endpoint | Create a real-time debug endpoint (always listed) |
list_realtime_endpoints | List real-time endpoints with connection URLs and live session counts |
list_realtime_sessions | List open and closed client sessions for an endpoint |
get_realtime_messages | Read a session's messages, or search across an endpoint's sessions |
send_realtime_message | Send a message to one client, or broadcast to every open session |
wait_for_realtime_message | Wait for a client message or a new session |
manage_realtime_rules | List, create, update, or delete auto-responder rules |
delete_realtime_endpoint | Preview or permanently delete a real-time endpoint |
create_realtime_endpoint and list_realtime_endpoints return each endpoint's connection_url. Socket.IO endpoints also get a socketio object (url, path, transports, token_via and a ready snippet). MQTT endpoints get an mqtt object (host, port, path, transport, protocol_versions, broker, mode, default_topic and auth). See Socket.IO and MQTT.
create_realtime_endpoint takes name, protocol (websocket, socketio, mqtt or sse), auth_token, upstream_url and on_connect_payload. For MQTT it also takes mqtt_broker: true (the default) routes publishes between the endpoint's clients, and false only captures them.
send_realtime_message sends to one session_id, or broadcasts when you leave it out. It takes payload, event_type, event_id and binary (a base64 payload sent as a binary frame), plus protocol fields:
| Field | Protocol | Description |
|---|---|---|
namespace | Socket.IO | Namespace to emit on (default /). The client must have connected it. |
spread_args | Socket.IO | Send a JSON array payload as one argument per element |
topic | MQTT | Topic to publish on, without + or #. Without one, the client's only plain subscription, else hooklistener. In broker mode a broadcast reaches only clients subscribed to it. |
qos | MQTT | 0 (default), 1 or 2 |
retain | MQTT | Set the RETAIN flag. On broker endpoints the message also becomes the topic's retained message. |
Text payloads may contain {{variables}} such as {{uuid}} or {{now}}; the tool renders them before sending. See Templating.
delete_realtime_endpoint closes the endpoint's open sessions with 1001, then permanently deletes the endpoint with its sessions, messages, rules and scenarios. Call it with dry_run: true to preview what would be deleted, including the number of open sessions, and with confirmed: true to delete. It is in the realtime toolset and needs write access: a Full access grant, or an API key with the write scope. Read-only grants are refused.
Email
Test inboxes for signup, login and other emails, and forwarding received email to webhooks. See Test emails with AI agents.
| Tool | Description |
|---|---|
create_inbox | Create a test inbox (always listed) |
list_inboxes | List inboxes with their addresses, email counts and webhook forwards |
list_emails | List captured emails for an inbox, newest first, with filters |
get_email | Get a captured email with its likely code, verification_link, codes, links and attachments |
wait_for_email | Wait for a matching email to arrive, or return one that already arrived after since |
delete_emails | Preview or permanently delete one email, or every email in an inbox |
delete_inbox | Preview or permanently delete an inbox and its emails |
set_inbox_forward | Create or update a webhook forward that POSTs each received email to a URL |
delete_inbox_forward | Preview or permanently delete a webhook forward |
Common email fields:
| Field | Used by | Description |
|---|---|---|
inbox_id | All but create_inbox and list_inboxes | Email inbox ID |
since | wait_for_email, list_emails | Only emails after this: an ISO 8601 timestamp with a UTC offset, or an email ID from the inbox. wait_for_email returns a matching email that already arrived at once |
to | wait_for_email, list_emails, set_inbox_forward | Exact recipient, case-insensitive. Use a unique plus-address per run (<slug>[email protected]) |
from | wait_for_email, list_emails, set_inbox_forward | Case-insensitive substring of the From header |
subject_contains | wait_for_email, list_emails, set_inbox_forward | Case-insensitive substring of the subject |
timeout | wait_for_email | Seconds to wait, default 30, max 60 |
blocking | wait_for_email | Wait in the call instead of returning a task receipt. By default the tool returns at once and the result is read from hooklistener://tasks/{task_id} |
include_text | get_email, wait_for_email | Add text, a readable plain-text rendering of the email |
include_body | get_email, wait_for_email | Add the full text and HTML bodies |
include_raw_headers | get_email, wait_for_email | Add the parsed headers and every header in order |
include_raw | get_email, wait_for_email | Add the raw email source |
email_id | get_email, delete_emails | Email ID. delete_emails without it clears the whole inbox |
forward_id | set_inbox_forward, delete_inbox_forward | Forward to update or delete. set_inbox_forward without it creates a forward |
url | set_inbox_forward | Public http(s) URL that receives each email |
dry_run, confirmed | Delete tools | Preview the deletion, or confirm it |
For wait_for_email, include_text applies to blocking and async waits; the other include_* fields apply to blocking waits only.
Email resources:
| Resource | Contents |
|---|---|
hooklistener://email/inboxes | The organization's inboxes |
hooklistener://email/inboxes/{inbox_id}/messages | Recent emails of an inbox |
hooklistener://email/messages/{email_id} | One email, as get_email returns it |
hooklistener://email/messages/{email_id}/body | Full text and HTML bodies |
hooklistener://email/messages/{email_id}/headers | Parsed headers and every header in order |
hooklistener://email/messages/{email_id}/attachments/{index} | One attachment: text for text/* types, base64 otherwise, up to 1 MiB |
Monitors
| Tool | Description |
|---|---|
create_monitor | Create an uptime monitor (always listed) |
list_monitors | List uptime monitors |
get_monitor_status | Get uptime, status, and recent checks for a monitor |
update_monitor | Update monitor configuration |
delete_monitor | Preview or permanently delete a monitor |
Tunnels
Tunnel investigation tools require a finite grant created through the authenticated Hooklistener API. MCP cannot create or broaden grants.
| Tool | Description |
|---|---|
plan_tunnel_action | Plan a tunnel action without changing state |
read_tunnel_capture_sensitive | Read sensitive capture evidence with an exact scoped grant |
add_tunnel_case_capture | Add a capture to a case after explicit confirmation |
replay_tunnel_capture | Replay a capture after explicit confirmation |
Removed tools
search_requests: uselist_requestswithqueryor an event, status, or time filter.forward_request: usereplay_requestwithtarget_url.- Datastore and endpoint action tools are no longer available. Use replay cases for repeatable webhook integration testing, and secrets for encrypted configuration values.