v0.4.0

Summary

0.4.0 lets Claude Code hear about events between prompts. Install the Claude Code plugin and ask Claude to watch for any event your bridge offers, such as new issues and comments on a repository your GitHub provider covers, or inbound email through Resend. Each event wakes Claude as it happens, even when it's idle, and a new session first catches up on what it missed (up to 24 hours). Under it is mcp-events-bridge watch, which polls the bridge and prints one JSON line per event, for any agent that wakes on a command's output. Nothing changes for a running bridge.

Upgrading from 0.3.0

1. Claude Code: /plugin install mcp-events-bridge --marketplace hookdeck/mcp-events-bridge (Claude Code 2.1.275 or later), and enter your bridge's MCP URL when asked. See the guide.
2. ChatGPT: if it can't subscribe to an event the bridge lists, refresh the plugin in ChatGPT's Plugins (#43).

Added

• mcp-events-bridge watch <event...> (#45): polls a running bridge and prints one JSON line per event, from now on, for agents that wake on a command's output, such as Claude Code's Monitor tool. See Polling.
• watch --list <file> and mcp-events-bridge watches add|remove|list (#47): watch follows a watch list as it changes, saves each watch's cursor, and resumes there next time (events up to 24 hours old). A watch that can't run, or a bridge that can't be reached, is reported on stdout as { "problem": ... }.
• Claude Code plugin (#26, #47; plugins/mcp-events-bridge, installed with /plugin install mcp-events-bridge --marketplace hookdeck/mcp-events-bridge): a monitor that runs watch on the project's watch list for the whole session, a skill for "watch…", "stop watching…" and "what am I watching?", and the bridge as an MCP server. See the guide.

Changed

• @modelcontextprotocol/client is a dependency (it was a dev dependency), for watch.

Fixed

• Docs: ChatGPT keeps the events it can subscribe to from when the plugin was added, so refresh the plugin after upgrading the bridge or adding a provider (#43). Connecting Claude Code, with screenshots (#46).

Full changelog: v0.3.0...v0.4.0 · CHANGELOG.md

v0.3.0

Summary

0.3.0 adds poll mode: MCP clients that can't receive webhooks, or don't support MCP Events yet, can now get events from the bridge by polling. Clients that implement MCP Events poll mode call events/poll; any other MCP client, such as Claude Code, Codex or Cursor, uses the new wait_for_event and poll_events tools. Nothing to change in your config: upgrade, restart serve (or redeploy), and add the bridge to your agent as an HTTP MCP server (Claude Code: see the guide).

Added

• Poll mode (#26): events/poll, for clients that can't receive webhooks, answered from Event Gateway's request history with no event store in the bridge. events/list offers poll. See Polling.
• poll_events and wait_for_event tools, the same polling for MCP clients without MCP Events support, such as Claude Code: wait_for_event returns as soon as there are events, or after up to 50 seconds.

Fixed

• GitHub: switching from manual mode to automatic registration no longer deletes the webhooks setup just created. The old registration was removed by source URL, which the new webhooks share.

Changed

• The capability is also advertised as extensions["io.modelcontextprotocol/events"], as in the MCP Events SEP (SEP-3415), alongside events.

Full changelog: v0.2.1...v0.3.0 · CHANGELOG.md

v0.2.1

Summary

0.2.1 fixes the rough edges a from-scratch run of 0.2.0 found: the secret line setup prints now pastes cleanly into .env, and providers add webhook --write-config creates bridge.config.ts when you don't have one yet. The docs now say plainly that each bridge needs its own Hookdeck project. It's also the first release published from GitHub Actions, with npm provenance.

Fixed

• setup prints the generated BRIDGE_MCP_SECRET= line unindented, so copying it as printed doesn't add spaces to .env.
• providers add webhook --write-config creates bridge.config.ts when there isn't one, instead of printing the entry.
• Docs: BRIDGE_DEPLOYMENT doesn't keep bridges sharing a Hookdeck project apart (they share provider sources, subscriptions and tunnel URLs): give each bridge its own project (#13). The tunnel URL reference shows the headers a hand-written MCP client sends.

Changed

• Published from GitHub Actions with npm provenance, when a GitHub Release is created.

Full changelog: v0.2.0...v0.2.1 · CHANGELOG.md

v0.2.0

Summary

0.2.0 brings the bridge to agents on your own machine and to webhooks from any sender, and adds an Agent Skill so a coding agent can set it up. It breaks compatibility with 0.1.0 on purpose: event names change, and agents subscribe again.

Upgrading from 0.1.0

1. npm install @hookdeck/mcp-events-bridge@0.2.0
2. In bridge.config.ts, list GitHub events by GitHub's own names: events: ['issues'], not ['github.issues'].
3. Run npx mcp-events-bridge setup, then restart serve (or redeploy).
4. Agents subscribe again, with a name from events/list: email.received is now resend.email.received. Ask ChatGPT to subscribe again. serve logs each old subscription it no longer serves.
5. Agents calling the tools: get_event needs the event's name as well as its id, and list_recent_events is now list_events.

Breaking

0.2.0 breaks compatibility with 0.1.0 deliberately, with no migration paths: 0.1.0 was an early demo release, as far as we know used only by this project.

• Event names are {instance id}.{event} (#15): the provider instance's id, then the provider's own name for the event. email.received is now resend.email.received; GitHub's names are unchanged with the default id (github.issues), and an instance with another id offers <id>.issues. Two instances can now offer the same event.
• No migration from 0.1.0. Subscriptions to renamed events get nothing (serve logs each subscription to an event it doesn't offer): agents, ChatGPT included, subscribe again with a name from events/list. Configs take the provider's own event names: events: ['issues'], not ['github.issues'].
• get_event(name, eventId): name is required. An event id is the provider's own, so two instances can share one; both are in every delivery and in list_events.
• list_recent_events is list_events. With a name, it searches only that instance.
• list_providers returns each provider's events as MCP names (resend.email.received, not email.received).

Added

• Local agents (#12): a local bridge gives agents on the same machine public tunnel URLs (create_tunnel_url, list_tunnel_urls), runs and supervises hookdeck listen for them, and re-sends deliveries they missed while listen was down. A tunnel URL covers the paths under it, for agents that build callback URLs from one base URL.
• Inbound recovery: a local bridge retries provider events that reached Event Gateway while it was stopped, and restarts its own hookdeck listen if it stops.
• Generic webhooks (#14): webhook({ id, verification, events, ... }) relays webhooks from any HTTP sender, verified by Event Gateway with HMAC, Standard Webhooks, Basic auth or an API key. mcp-events-bridge providers add webhook <id> creates the source, prints its URL and the config entry, and adds the secret's variable to .env (--write-config edits bridge.config.ts).
• Agent Skill: skills/mcp-events-bridge (npx skills add hookdeck/mcp-events-bridge), also in the npm package.
• Hermes Agent guide (experimental): references/hermes-agent.md runs Hermes's MCP Events pull request against a local bridge.

Changed

• deployment is optional. It defaults to BRIDGE_DEPLOYMENT, then local with CLI inbound or public with HTTP inbound. A config that sets it, as 0.1.0's examples did, keeps its resource names.
• setup exits 1 when a webhook secret isn't set yet, after setting up everything else, and labels the MCP endpoint "MCP URL".
• Inbound bodies that aren't JSON are answered 200 and ignored, so Event Gateway doesn't retry them.
• A local setup logs the Hookdeck CLI in to the bridge's project in .hookdeck/config.toml, as serve already did, so hookdeck commands run in the bridge's directory use that project from the start. Without the CLI, it says so and carries on (serve still needs it).
• BRIDGE_MCP_SECRET must be URL-safe (letters, digits, -, _, ., ~): it's part of the MCP URL, so setup and serve refuse anything else. Secrets setup generates, in 0.1.0 too, always are.
• setup prints a generated BRIDGE_MCP_SECRET= line on its own, ready to paste into .env; the Fly.io hint is only shown for HTTP inbound.

Fixed

• The MCP server's version (serverInfo.version) is the package version, not 0.0.0.

Full changelog: CHANGELOG.md

v0.1.0

Summary

The first release of the MCP Events bridge, published to npm as @hookdeck/mcp-events-bridge. It turns webhooks into MCP Events, so AI agents such as ChatGPT can act the moment something happens, such as an email arriving or an issue being opened. Hookdeck Event Gateway receives, verifies and delivers every event, and the bridge is stateless: each subscription is an Event Gateway connection, so there's no database.

npm install @hookdeck/mcp-events-bridge
npx mcp-events-bridge setup
npx mcp-events-bridge serve

MCP Events is an experimental MCP extension, and this 0.x package may change with it. See the README for the quick start, deploying to Fly.io and connecting ChatGPT.

New features

• MCP Events over webhook delivery. events/list, events/subscribe with the spec's signed endpoint challenge, and events/unsubscribe, plus get_event, list_recent_events and list_providers tools. Deliveries are signed per subscriber with Standard Webhooks, and Event Gateway retries them, dedupes them and keeps a record of every attempt. Failing callbacks are reported back as deliveryStatus, and a 410 ends the subscription.

• setup and serve CLI. setup creates the Event Gateway resources and provider webhooks, and is safe to re-run. serve checks the setup, then runs hookdeck listen for every provider when running locally, so a laptop needs no public URL. (#1)

• A bridge.config.ts config file. defineConfig and env(), loaded as TypeScript from ESM or CommonJS projects. (#3)

Supported providers

• Resend: inbound email as email.received, filtered by from and to. setup registers the Resend webhook for you.
• GitHub: one MCP event per GitHub webhook type (github.issues, github.pull_request, github.push and 23 more), filtered by repository, actions and sender. setup registers webhooks on a list of repositories or an organization with a token, or you add them by hand in manual mode, with no token. (#2)

Add others with defineProvider, for any service Event Gateway has a source type for. Each provider only needs its own configuration (see Configuration).

Known limitations

• One owner per bridge. The MCP endpoint is protected by a secret URL; OAuth is planned.
• Webhook delivery only. Poll delivery and local agents (through Event Gateway's new MCP Events source type) come next.
• Retries reuse the first signature. They're kept inside receivers' 5-minute window, until Event Gateway signs deliveries itself.

---

Full Changelog: https://github.com/hookdeck/mcp-events-bridge/commits/v0.1.0