Turning webhooks into MCP Events for @tanstack/ai-mcp

[leggetter]

@tanstack/ai-mcp's experimental MCP Events support (#1816) lets an agent subscribe to an MCP server's events, but few MCP servers send events yet. So I built an open-source MCP server that turns webhooks into MCP Events, and tested it with @tanstack/ai-mcp 1.0.0. The test listed the events, subscribed with a filter, received a signed delivery that the library verified, refreshed and unsubscribed.

The sources are Resend inbound email, GitHub, Hookdeck Event Gateway source types such as Stripe and Slack, and any service that signs its webhooks.

import { createMCPClient } from '@tanstack/ai-mcp';
import { createMCPEventWebhook, inMemoryMCPEventStore } from '@tanstack/ai-mcp/events';

const store = inMemoryMCPEventStore(); // use durable storage in production
const webhook = createMCPEventWebhook({
  store,
  onEvent: async ({ event, messageId, subscription }) => {
    // event.eventId, event.data
  },
});
// Serve POST <callback path> with: res <- await webhook(request)

const mcp = await createMCPClient({
  transport: { type: 'http', url: 'https://<bridge>/mcp', headers: { Authorization: `Bearer ${process.env.BRIDGE_MCP_SECRET}` } },
  experimental_events: { store },
});
const sub = await mcp.experimental_events.subscribe({
  name: 'resend.email.received',
  arguments: { from: 'alice@example.com' },
  delivery: { mode: 'webhook', url: 'https://<your callback URL>' },
});

A few things I hit along the way:

• TanStack AI rejects a delivery whose webhook-id isn't its eventId. The bridge sends the eventId as webhook-id, as ChatGPT and the AI SDK also expect. SEP-3415's latest text asks for a per-message id, so a server that follows it would fail here.
• It doesn't renew a subscription by itself, so call refresh({ key: sub.key }) before sub.refreshBefore.
• The store holds each subscription's signing secret. With the in-memory store, a restart loses them and the receiver answers 401, so use durable storage in production.
• For an agent on a laptop, the bridge creates a public callback URL on Event Gateway and uses the Hookdeck CLI to forward deliveries to localhost.

It's built on Hookdeck Event Gateway (I work at Hookdeck), so it needs a free Hookdeck account. Event Gateway receives and verifies the webhooks and delivers the events, and you run the bridge itself locally or deploy it. It's MIT.

• Repo: https://github.com/hookdeck/mcp-events-bridge
• TanStack AI setup: https://github.com/hookdeck/mcp-events-bridge/blob/main/skills/mcp-events-bridge/references/library-clients.md#tanstack-ai
• Demo (2:23): https://youtu.be/TmjbnuxesPQ

If the webhook-id check is meant to change as the SEP settles, I'm happy to test the bridge against a pre-release.