# Test MCP Events Deliveries Locally with the Hookdeck CLI

When you add [MCP Events](/webhooks/guides/what-are-mcp-events) to an MCP server, you need a subscriber to test against: a public `https` callback URL that answers the verification handshake, and somewhere to read each signed delivery. This guide sets one up with the [Hookdeck CLI](/docs/cli). You subscribe to your server with a Hookdeck URL, and `hookdeck listen` forwards each delivery to a receiver on your machine, where you can inspect the headers, check the signature and replay it.

MCP Events is a draft extension, proposed in [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415), and details may change before it's accepted.

## How it fits together

```mermaid
sequenceDiagram
    participant You
    participant Server as Your MCP server
    participant Source as Hookdeck MCP Events source
    participant CLI as hookdeck listen
    participant Receiver as Receiver on localhost

    You->>Source: 1. Create with secret
    You->>Server: 2. events/subscribe
    Server->>Source: 3. Signed challenge
    Source-->>Server: Challenge echoed
    Server-->>You: Subscription id
    Note over Server: Event happens
    Server->>Source: 4. Signed event
    Source-->>Server: 200, stored
    Source->>CLI: 5. Forward event
    CLI->>Receiver: Unchanged request
    Receiver-->>CLI: 200 or 400

```

1. You create an MCP Events source in Hookdeck. It holds the subscription's signing secret, and its URL becomes the callback URL.
2. You call `events/subscribe` on your MCP server with that URL and secret.
3. Your server sends a signed verification challenge to the URL. The source checks the signature and the timestamp, then echoes the challenge, so the subscription is created.
4. Your server delivers each event to the same URL. The source checks the signature again, stores the request and answers `200`.
5. `hookdeck listen` forwards the delivery, headers and body unchanged, to `localhost`. You read it in the terminal and in your receiver, and replay it as often as you like.

## What this tests, and what it doesn't

It tests what your server sends: the handshake, the Standard Webhooks headers and signature, the `X-MCP-Subscription-Id` header, the event envelope and your argument filters. It also tests your own receiver code, if you're building one.

It doesn't test your server's retries. Hookdeck answers `200` once it has stored a delivery, whatever happens on your machine, so your server never sees a failure. To check your retry schedule and your handling of `410` and `413`, use Outpost's [`mcp-dev check`](https://github.com/hookdeck/outpost/tree/main/cmd/mcp-dev), which runs SEP-3415's webhook rules against an MCP Events server.

## Prerequisites

* An MCP server that offers at least one event in webhook mode, running locally or deployed. Your server needs to reach Hookdeck's `https` URL; it doesn't need to be public itself.
* The Hookdeck CLI, installed and logged in (`npm install hookdeck-cli -g`, then `hookdeck login`). A free Hookdeck account is enough.
* Node.js 20 or later for the example receiver.

## Step 1: Create the test subscription's source

The subscriber supplies the signing secret. SEP-3415 requires `whsec_` followed by base64 that decodes to 24 to 64 bytes:

```bash
export SECRET="whsec_$(openssl rand -base64 32)"

```

Create an MCP Events source that holds the secret, and note its `id` and `url`:

```bash
hookdeck gateway source create --name mcp-events-test --type MCP_EVENTS \
  --webhook-secret "$SECRET" --output json

export SOURCE_URL=<the url from the output>

```

A source holds one secret, so use one source per test subscription.

## Step 2: Start a receiver and the CLI

The receiver prints each delivery's headers and verifies its signature with the [`standardwebhooks`](https://www.npmjs.com/package/standardwebhooks) library, the same check a real subscriber makes:

```js
// receiver.mjs
import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.SECRET);

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const raw = Buffer.concat(chunks).toString("utf8");
    const headers = {
      "webhook-id": req.headers["webhook-id"] ?? "",
      "webhook-timestamp": req.headers["webhook-timestamp"] ?? "",
      "webhook-signature": req.headers["webhook-signature"] ?? "",
    };
    console.log(headers, "subscription:", req.headers["x-mcp-subscription-id"]);
    try {
      webhook.verify(raw, headers); // checks the signature and the 5-minute window
      console.log("signature OK", JSON.parse(raw));
      res.writeHead(200).end();
    } catch (error) {
      console.log("signature FAILED:", error.message);
      res.writeHead(400).end();
    }
  });
}).listen(4000);

```

Run it with the same `SECRET`, then start the CLI in a second terminal:

```bash
npm install standardwebhooks
node receiver.mjs

# second terminal
hookdeck listen 4000 mcp-events-test

```

`listen` finds the MCP Events source and connects it to a new CLI destination, `cli-mcp-events-test`, with no rules. That suits testing: without the deduplicate rule you'd use in production, you see every request your server sends, duplicates included.

Create the source before you start `listen`. If no source of that name exists, `listen` creates a plain one, which can't answer the handshake.

## Step 3: Subscribe, and watch the handshake

Call `events/subscribe` on your server with the source URL and the secret. Any MCP client that supports MCP Events works. With `curl` against a server on protocol version `2026-07-28`:

```bash
curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: events/subscribe" \
  -H "Mcp-Name: order.created" \
  -d @- <<EOF
{
  "jsonrpc": "2.0", "id": 1, "method": "events/subscribe",
  "params": {
    "name": "order.created",
    "arguments": { "currency": "USD" },
    "delivery": { "mode": "webhook", "url": "$SOURCE_URL", "secret": "$SECRET" },
    "ttlMs": 3600000,
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "curl", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": { "io.modelcontextprotocol/events": {} }
      }
    }
  }
}
EOF

```

Before your server answers, it sends the challenge to the source. If the signature verifies and `webhook-timestamp` is within 5 minutes, the source echoes the challenge, and `curl` prints the subscription's `id` and `refreshBefore`:

```json
{"result":{"resultType":"complete","id":"sub_1d5fb712e33e66946e2abe96cc677e76","refreshBefore":"2026-11-17T15:03:41Z","cursor":null,"truncated":false,...},"jsonrpc":"2.0","id":1}

```

The handshake is answered at the source. It doesn't reach your receiver, and a handshake that passes isn't kept in the request log.

If you'd rather use a client than `curl`, the Outpost demo's test subscriber takes the source URL and secret, and runs its own receiver on port 4000 that verifies each delivery. Stop `receiver.mjs` first, then run, from a checkout of the [demo](https://github.com/hookdeck/mcp-events-outpost-demo):

```bash
MCP_SERVER_URL=http://localhost:3000/mcp MCP_TOKEN=<token> \
  npm run client -- --currency USD --callback-url "$SOURCE_URL" --secret "$SECRET"

```

### If the handshake fails

If the subscribe fails with `-32027` (CallbackEndpointError), the source rejected the handshake with `401` and the body `{"error":"Invalid signature"}`. Outpost, for example, reports it as `"data":{"reason":"challenge_failed"}`. Rejected handshakes are kept in the request log as unverified, with the rejection cause `VERIFICATION_FAILED`. Find yours in the dashboard or with:

```bash
hookdeck gateway request list --source-id <source id> --verified false

```

Open one with `hookdeck gateway request get <request id>` to see the headers and body your server sent, then check the usual causes. The source answers `Invalid signature` for all of them:

| What you find | Likely cause |
| --- | --- |
| The timestamp is current | Signing with the wrong secret; signing re-serialized JSON instead of the exact bytes sent; signing something other than `webhook-id.webhook-timestamp.body`; or using the secret without base64-decoding the part after `whsec_` |
| The timestamp is 13 digits, or more than 5 minutes off | `webhook-timestamp` in milliseconds, or a clock that's wrong. A correct signature over a bad timestamp still gets `401` |
| No request in the log | Your server didn't send a handshake, or refused the URL before trying |

## Step 4: Trigger an event and inspect it

Do whatever makes your server emit the event, such as placing an order. The delivery appears as a line in the `hookdeck listen` terminal:

```text
2026-11-17 14:21:27 [200] POST http://localhost:4000/ (7ms) → https://dashboard.hookdeck.com/events/evt_oJSElCJ2d3pUGLadT4

```

Select it and press `d` to see the full request; `H` copies the headers, `B` the body and `C` the whole request. The CLI forwards your server's headers and body unchanged, and adds its own `X-Hookdeck-*` headers and an `Idempotency-Key`.

Check each part against SEP-3415:

| Part | What to check |
| --- | --- |
| `webhook-id` | Present, and the same on every retry of this delivery. SEP-3415 makes it a per-delivery ID; OpenAI's guide expects it to equal `eventId` |
| `webhook-timestamp` | Unix seconds, new on every attempt |
| `webhook-signature` | `v1,<base64>`; one entry per valid secret during rotation |
| `X-MCP-Subscription-Id` | Equal to the `id` that `events/subscribe` returned |
| Body | `eventId`, `name`, `timestamp`, `data` and `cursor`; `data` matches your `payloadSchema`; 256 KiB or less |

Your receiver's output confirms the signature from the subscriber's side. A pass there means the bytes reached your machine exactly as your server signed them:

```text
{
  'webhook-id': 'msg_QXjPq9mP9LJsmGG0raccNA',
  'webhook-timestamp': '1794924318',
  'webhook-signature': 'v1,gpFPrVE0wUdspoWSqsfFsymLwKPnVZzFBrWORP0WPvo='
} subscription: sub_1d5fb712e33e66946e2abe96cc677e76
signature OK {
  eventId: 'evt_ord_0ec73f7bb097_e9ed9aa8',
  name: 'order.created',
  timestamp: '2026-11-17T14:05:18.297Z',
  data: { orderId: 'ord_0ec73f7bb097', total: 150, currency: 'USD', highValue: true, ... },
  cursor: null
}

```

Then check your filters: trigger an event that doesn't match the subscription's `arguments`, such as an order in EUR. Nothing should arrive, and the source's request log should show no new request.

## Step 5: Replay deliveries

You don't need to trigger a new order every time you change your receiver. Replay a stored delivery instead:

* In the `hookdeck listen` terminal, select the delivery and press `r`.
* From any terminal, run `hookdeck gateway event retry <event id>`, using the `evt_...` ID at the end of the line's dashboard link.

A replay forwards the stored request, headers included, so it tests two receiver rules:

* **Duplicates.** The replay carries the same `webhook-id`. A receiver that deduplicates should acknowledge it and not process it again.
* **The 5-minute window.** The replay keeps the original `webhook-timestamp`. Replay a delivery more than 5 minutes old, and the example receiver rejects it with `Message timestamp too old`, as SEP-3415 recommends. To check the payload handling instead, skip the timestamp check while you test.

## Step 6: Test refreshes and unsubscribes

Call `events/subscribe` again with the same name, arguments, URL and secret. Your server should return the same `id` with a later `refreshBefore`. Whether it sends a new handshake depends on your server: Outpost, for example, remembers a passed check for each callback URL and doesn't repeat it. A passed handshake isn't kept in the request log, so check your server's own logs to see whether it sent one.

Then call `events/unsubscribe` with the same name, arguments and URL, trigger another matching event, and check that nothing arrives.

## If the CLI wasn't running

While no `hookdeck listen` is connected, Hookdeck still stores each request but creates no event for it, and logs it as ignored. Your server still sees `200`. Find the request with `hookdeck gateway request list --source-id <source id>`, and once the CLI is running again, retry it:

```bash
hookdeck gateway request retry <request id>

```

## Clean up

Unsubscribe, stop `listen`, then delete the source so nothing else can deliver to it. That removes the connection too, but not the CLI destination `listen` created, so delete that as well:

```bash
hookdeck gateway source delete <source id> --force
hookdeck gateway destination list --name cli-mcp-events-test
hookdeck gateway destination delete <destination id> --force

```

## Limits

* Your server's retries aren't exercised. Hookdeck answers `200` once it has stored a delivery, so failures on your machine never reach your server. Use [`mcp-dev check`](https://github.com/hookdeck/outpost/tree/main/cmd/mcp-dev) for retry and `410`/`413` handling.
* Event deliveries aren't checked for freshness at the source, only the handshake is. Your receiver applies the 5-minute window.
* A source holds one secret, so you can't test secret rotation, where your server signs with both the old and new secret for a while.
* Requests over 2.5 MiB are verified after the `200`, so a bad signature on one doesn't reach your server as a failure. SEP-3415 says delivery bodies should be 256 KiB or less.
* This tests webhook mode only. Poll and push delivery don't use a callback URL.

## Related resources

* [What are MCP Events?](/webhooks/guides/what-are-mcp-events)
* [MCP Events guides and demos](/webhooks/guides/mcp-events), Hookdeck's hub for MCP Events
* [Use Event Gateway as a forward proxy for MCP Events](/docs/guides/how-to-use-event-gateway-as-mcp-events-forward-proxy), for agents that receive events in production
* [Send MCP Events webhooks with Outpost](/docs/outpost/guides/send-mcp-events-webhooks-with-outpost), to have Outpost handle delivery for your server
* [Hookdeck CLI reference](/docs/cli)