hookdeck-cli 1.9.1 → 1.10.0-beta.2

package/README.md

@@ -8,12 +8,49 @@ Using the Hookdeck CLI, you can forward your events (e.g. webhooks) to your loca
 
 Hookdeck CLI is compatible with most of Hookdeck's features, such as filtering and fan-out delivery. You can use Hookdeck CLI to develop or test your event (e.g. webhook) integration code locally.
 
+You can also manage Hookdeck Event Gateway resources—sources, destinations, connections, events, transformations—from the CLI. For AI and agent workflows, the Event Gateway MCP server (`hookdeck gateway mcp`) exposes these capabilities as tools in MCP-compatible clients (e.g. Cursor, Claude).
+
 Although it uses a different approach and philosophy, it's a replacement for ngrok and alternative HTTP tunnel solutions.
 
 Hookdeck for development is completely free, and we monetize the platform with our production offering.
 
 For a complete reference of all commands and flags, see [REFERENCE.md](REFERENCE.md).
 
+## Table of contents
+
+- [Installation](#installation)
+  - [NPM](#npm)
+  - [macOS](#macos)
+  - [Windows](#windows)
+  - [Linux Or without package managers](#linux-or-without-package-managers)
+  - [Docker](#docker)
+- [Usage](#usage)
+- [Commands](#commands)
+  - [Login](#login)
+  - [Listen](#listen)
+  - [Logout](#logout)
+  - [Skip SSL validation](#skip-ssl-validation)
+  - [Disable health checks](#disable-health-checks)
+  - [Version](#version)
+  - [Completion](#completion)
+  - [Running in CI](#running-in-ci)
+  - [Event Gateway](#event-gateway)
+  - [Event Gateway MCP](#event-gateway-mcp)
+  - [Manage connections](#manage-connections)
+  - [Transformations](#transformations)
+  - [Requests, events, and attempts](#requests-events-and-attempts)
+  - [Manage active project](#manage-active-project)
+- [Configuration files](#configuration-files)
+- [Global Flags](#global-flags)
+- [Troubleshooting](#troubleshooting)
+- [Developing](#developing)
+- [Testing](#testing)
+- [Releasing](#releasing)
+- [Repository Setup](#repository-setup)
+- [License](#license)
+
+**Quick links:** [Local development (Listen)](#listen) · [Resource management (CLI)](#event-gateway) / [Manage connections](#manage-connections) · [AI / agent integration (Event Gateway MCP)](#event-gateway-mcp)
+
 https://github.com/user-attachments/assets/7a333c5b-e4cb-45bb-8570-29fafd137bd2
 
 
@@ -491,6 +528,83 @@ hookdeck gateway transformation run --code "addHandler(\"transform\", (request,
 
 For complete command and flag reference, see [REFERENCE.md](REFERENCE.md).
 
+### Event Gateway MCP
+
+The CLI includes an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server for investigating event traffic in production. It exposes read-only tools that let AI agents query your Hookdeck Event Gateway — inspect connections, trace requests through events and delivery attempts, review issues, and pull aggregate metrics.
+
+**Configure your MCP client** (Cursor, Claude Desktop, or any MCP-compatible host):
+
+Cursor (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "hookdeck": {
+      "command": "hookdeck",
+      "args": ["gateway", "mcp"]
+    }
+  }
+}
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "hookdeck": {
+      "command": "hookdeck",
+      "args": ["gateway", "mcp"]
+    }
+  }
+}
+```
+
+The client starts `hookdeck gateway mcp` as a stdio subprocess. If you haven't authenticated yet, the `hookdeck_login` tool is available to log in via the browser.
+
+#### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `hookdeck_projects` | List projects or switch the active project for this session |
+| `hookdeck_connections` | Inspect connections and control delivery flow (list, get, pause, unpause) |
+| `hookdeck_sources` | Inspect inbound sources (HTTP endpoints that receive events) |
+| `hookdeck_destinations` | Inspect delivery destinations (HTTP endpoints where events are sent) |
+| `hookdeck_transformations` | Inspect JavaScript transformations applied to event payloads |
+| `hookdeck_requests` | Query inbound requests — list, get details, raw body, linked events |
+| `hookdeck_events` | Query processed events — list, get details, raw payload body |
+| `hookdeck_attempts` | Query delivery attempts — retry history, response codes, errors |
+| `hookdeck_issues` | Inspect aggregated failure signals (delivery failures, transform errors, backpressure) |
+| `hookdeck_metrics` | Query aggregate metrics — counts, failure rates, queue depth over time |
+| `hookdeck_help` | Discover available tools and their actions |
+
+#### Example prompts
+
+Once the MCP server is configured, you can ask your agent questions like:
+
+```
+"Are any of my events failing right now?"
+→ Agent uses hookdeck_issues to list open issues, then hookdeck_events to inspect recent failures.
+
+"Show me the last 10 events for my Stripe source and check if any failed."
+→ Agent uses hookdeck_sources to find the Stripe source, then hookdeck_events filtered by source and status.
+
+"What's the error rate for my API destination over the last 24 hours?"
+→ Agent uses hookdeck_metrics with measures like failed_count and count, grouped by destination.
+
+"Trace request req_abc123 — what events did it produce, and did they all deliver successfully?"
+→ Agent uses hookdeck_requests to get the request, then the events action to list generated events.
+
+"Why is my checkout endpoint returning 500s? Show me the latest attempt details."
+→ Agent uses hookdeck_events filtered by status FAILED, then hookdeck_attempts to inspect delivery details.
+
+"Pause the connection between Stripe and my staging endpoint while I debug."
+→ Agent uses hookdeck_connections to find and pause the connection.
+
+"Compare failure rates across all my destinations this week."
+→ Agent uses hookdeck_metrics with dimensions set to destination_id and measures like error_rate.
+```
+
 ### Manage connections
 
 Create and manage webhook connections between sources and destinations with inline resource creation, authentication, processing rules, and lifecycle management. Use `hookdeck gateway connection` (or the backward-compatible alias `hookdeck connection`). For detailed examples with authentication, filters, retry rules, and rate limiting, see the complete [connection management](#manage-connections) section below.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookdeck-cli",
-  "version": "1.9.1",
+  "version": "1.10.0-beta.2",
   "description": "Hookdeck CLI",
   "repository": {
     "type": "git",