[leggetter]

A demo of Hookdeck Event Gateway acting as the forward proxy that MCP Events (SEP-3415, a draft MCP extension) describes for webhook delivery, in hookdeck/mcp-events-forward-proxy/. Verified against a dedicated Event Gateway test project, last on 2026-10-14 after Event Gateway's MCP Events handshake changes: 7 of 7 scenarios locally and 6 of 6 deployed.

• Stand-in sender (src/sender/): an MCP server offering incident.created in webhook mode, standing in for any third-party MCP server.
• Agent (src/agent/): an MCP client that owns its proxy. Per subscription it creates an MCP Events source with a fresh whsec_ secret and a connection (dedup on headers.webhook-id, retries), subscribes with the source URL, refreshes, and cleans up on exit.
• Two delivery paths: locally through hookdeck listen (no public URL), and deployed over HTTP to the agent's endpoint, which checks x-hookdeck-signature.
• Recovery when listen was down (src/agent/recover.ts): on start and on reconnect, the agent retries CLI_DISCONNECTED requests and settled FAILED events, and leaves anything queued or scheduled to Event Gateway. With --keep, a restarted agent picks up its existing source and subscription.
• npm run scenarios: runs the scenarios and prints pass or fail with evidence: 7 locally (CLI), 6 deployed (HTTP). The deployed agent was last deployed on 2026-10-08; no later commit changes how the agent or sender behaves (only the MCP client's name).
• A second sender: run unchanged (env vars only) against the Outpost demo's MCP server, with Outpost doing the delivery: filtering, a 503 retried by Event Gateway, and a clean listen stop recovered.
• evdock spike: evdock's daemon receives through an MCP Events source and hookdeck listen with one small evdock change (a supplied secret); deliveries held over 5 minutes fail its timestamp check. Results in docs/PLAN.md (Phase 3).
• Known limits stated in the README: an MCP client needs code to set up the proxy, the agent holds the project's API key, there's one source per subscription because a source holds one secret, nothing rejects a stale event (Event Gateway checks freshness on the challenge only), and the CLI path is for local development.
• Also: a hookdeck/mcp-events-outpost stub linking the sending-side demo, and rows for both in the repo README.
• Deployment: Fly.io config for the agent and sender. The apps are named mcp-events-receive-*, from the demo's earlier name; a comment in each fly.*.toml says so.

Verified results

First run 2026-10-08; the rows npm run scenarios covers re-run 2026-10-14. The rows marked by hand in the README weren't re-run.

Scenario	Local (CLI)	Deployed (HTTP)
Agent creates the source; the sender's challenge is answered by Event Gateway	Yes	Yes
Normal event	Handled, attempt 1	Handled, attempt 1
Duplicate (same webhook-id, re-signed)	Handled once; second request ignored by dedup	Same
Badly signed delivery	VERIFICATION_FAILED, never delivered; sender saw 200	Same
Agent answers 503, then recovers	Retried every 15 s, then handled	Handled on attempt 2; sender saw one 200
Forged request straight to the agent	n/a	401
Refresh before refreshBefore	Yes	Yes, with deliveryStatus; one subscription kept for over 6 days
Ctrl+C	Unsubscribes, stops listen, deletes source and connection	n/a
listen stopped cleanly, then back	CLI_DISCONNECTED; recovery retried the request; handled once	n/a
listen killed, back after 30 s	Retry rule delivered attempt 3; recovery left it alone; handled once	n/a
listen killed until retries ran out	Settled FAILED; recovery retried it; handled once	n/a
Agent stopped with --keep, events sent, restarted	Same source and subscription; both requests recovered; each handled once	n/a

🤖 Generated with Claude Code