MCP Events bridge

MCP Events bridge

Turn webhooks into MCP Events, so AI agents can act the moment something happens: an email arrives, an issue is opened, a workflow fails. Hookdeck Event Gateway receives, verifies and delivers every event.

For example, an email arrives at a Resend address, and ChatGPT, subscribed through the bridge, acts on it:

Why

MCP Events is an experimental MCP extension that lets an agent subscribe to events instead of polling for them, and ChatGPT supports it. But an agent can only subscribe to MCP servers that implement it, and almost none do yet, while nearly every service already sends webhooks.

The bridge closes that gap:

• Webhooks become MCP Events. Sources: Resend inbound email, GitHub, any of 163 Event Gateway source types (Stripe, Slack, Shopify and more), and webhooks from any HTTP sender, such as a service you've built, verified with HMAC, Standard Webhooks, Basic auth or an API key. Add others with defineSource.
• Subscribers choose what wakes them. Events have filters, such as an email's sender, or a GitHub repository and action.
• Every event verified, delivered and recorded. Event Gateway verifies each service's signatures, retries failed deliveries, drops duplicates within an hour, and keeps a record of every event and attempt.
• Stateless. Each subscription is an Event Gateway connection, so there's no database.

It's for developers who want agents (ChatGPT, Claude Code, Hermes Agent and others) to react to events from the services they already use.

Status: 0.9, an open-source project. MCP Events is experimental, and this package may change with it. We're building the same thing into Hookdeck Event Gateway, so tell us what you need. See docs/PLAN.md for what's done and what's next, and CHANGELOG.md for changes between versions. Upgrading from 0.7: see docs/UPGRADING.md.

How it works

• Event Gateway verifies each service's webhook signature, keeps every request, turns each one into an MCP Event, and delivers it to each subscriber, signed with the subscriber's secret, with retries.
• The bridge is the MCP server: it lists the events on offer, handles subscribe (including the spec's endpoint challenge), and manages one Event Gateway connection per subscription. Events don't pass through it.
• The Hookdeck CLI forwards MCP Events to local agents, and Event Gateway's notifications to a bridge on your laptop, so neither needs a public URL of its own.

The design, its trade-offs and how it maps to the spec are in docs/ARCHITECTURE.md.

Supported MCP clients

Clients that support MCP Events subscribe to the bridge, and receive each event as a webhook at their callback URL. Clients that don't, such as Claude Code, poll with the bridge's tools.

Versions are the ones tested against the bridge, in October and November 2026. MCP Events support is experimental in Hermes Agent and in the three libraries. Codex and Cursor's CLI were tested non-interactively, and each needs the bridge's tools allowed before it can call them: see the guide.

Set up with a coding agent

The mcp-events-bridge skill walks a coding agent (Claude Code, Cursor, Codex and others that support Agent Skills) through setup, adding sources, connecting an agent and troubleshooting, with a success signal for each step:

npx skills add hookdeck/mcp-events-bridge

Then ask the agent to set up the bridge. It asks you for the credentials. The skill is also in the npm package, under skills/.

Quick start

You need:

• Node 22.12 or later.
• A Hookdeck account and a project for the bridge. From the project's settings (Secrets): the API key and the signing secret.
• The Hookdeck CLI, for running the bridge locally (and for npm run e2e).
• At least one source: a Resend or GitHub account, or any service that sends webhooks, including your own.

1. Create a project and install the bridge:

   mkdir my-bridge && cd my-bridge

npm init -y && npm pkg set type=module npm install @hookdeck/mcp-events-bridge printf 'node_modules/\n.env\n.hookdeck/\n' > .gitignore # .env and .hookdeck/ hold credentials

1. Choose sources in bridge.config.ts:

   import { defineConfig, env } from '@hookdeck/mcp-events-bridge';

import { github, resend } from '@hookdeck/mcp-events-bridge/sources';

export default defineConfig({ sources: [ resend({ apiKey: env('RESEND_API_KEY') }), // Only setup uses the token, so it's optional here: a deployed bridge runs without it. github({ token: env('GITHUB_TOKEN', { optional: true }), scope: { repos: ['your-org/your-repo'] } }), ], });

Keep only the sources you use, or add others, such as Stripe or your own service: see Sources.

1. Add credentials to .env:

   HOOKDECK_API_KEY=...

HOOKDECK_SIGNING_SECRET=... RESEND_API_KEY=... # if you use Resend GITHUB_TOKEN=... # if you use GitHub

1. Create the Event Gateway resources and the webhooks:

   npx mcp-events-bridge setup

The first run generates an MCP secret: add it to .env as BRIDGE_MCP_SECRET. Setup is safe to re-run, and updates the webhooks when you add sources or change events or repositories. A Resend or GitHub webhook deleted at the service is registered again. Removing a source or a repository deletes nothing: delete its webhook (and its Event Gateway source) yourself. Upgrading from 0.7, setup offers to migrate your subscriptions: see docs/UPGRADING.md.

1. Run the bridge:

   npx mcp-events-bridge serve

Locally, serve checks that setup has run, and starts hookdeck listen for Event Gateway's notifications (which tell the bridge about failing callbacks) and for local agents; it restarts listen if it stops. Events don't pass through the bridge: Event Gateway delivers each one to its subscribers, so none are lost while the bridge is stopped. Once an agent has subscribed, send an email to your Resend address, or open an issue, and its delivery shows under the subscription's connection, mcp-sub- , in the Event Gateway dashboard.

1. Connect an agent: see Connect ChatGPT, Connect Claude Code, or Supported MCP clients for the others. ChatGPT has to reach the bridge's MCP endpoint, so deploy the bridge, or expose your local port with a tunnel such as cloudflared tunnel --url http://127.0.0.1:8080 and use https:// /mcp/ . Events don't need the tunnel: Event Gateway delivers them to ChatGPT directly.

Connect ChatGPT

With Developer mode on (ChatGPT Plus or above), go to Plugins, choose Add > Create MCP App, paste https:// /mcp/ , and choose No Authentication. ChatGPT can't send an Authorization header (it offers only OAuth or no authentication), so it takes the secret in the URL. Then, in a Work chat, ask to be told about new events, for example emails from a particular sender. ChatGPT subscribes and sets up a monitoring task:

When an event arrives, the task runs with it, as in the screenshot at the top. A chat that's open shows it on its own, about a minute after the event arrives, even though ChatGPT answers the delivery within about 2 seconds (seen on 28 Oct, in an open, focused tab); if it doesn't appear, reload the page. Pausing the task unsubscribes it from the bridge, and resuming it subscribes again from now, with a new callback URL and no cursor, so events that arrive while it's paused aren't delivered or replayed (seen on 27 Oct). They're still in Event Gateway, so ChatGPT can list them with list_events.

ChatGPT keeps the list of events it can subscribe to from when you added the plugin. After you upgrade the bridge or add a source, refresh