Skip to content
Source
Sign inSign up
TanStack/ai

fix(ai-mcp): accept MCP Events deliveries whose webhook-id differs from eventId #2150

Openleggetter(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromrefs/pull/2150/headopened View on GitHub

createMCPEventWebhook returns 400 for every event from a server that follows SEP-3415. The receiver requires the webhook-id header to equal the eventId in the body, but SEP-3415 says that webhook-id "MUST NOT be derived from eventId". This PR removes that check, so the receiver accepts both forms.

🎯 Changes

  • packages/ai-mcp/src/events/webhook.ts: the receiver no longer compares webhook-id with eventId. The check on the event name stays.
  • Unit tests: one test for each webhook-id form, and one test for one event on two subscriptions.
  • The shared test events server (tests/helpers/events-server.ts) now sends a per-message webhook-id for events. It already did this for gap, terminated and verification envelopes. The client tests and the Playwright mcp-events.spec.ts now run with the SEP form.
  • E2E: the testing/e2e app records the messageId that onEvent gets. The subscribe and emit test checks that the webhook-id is a msg_ id and that the event keeps its own evt_ eventId.
  • Changeset: patch for @tanstack/ai-mcp.

No docs change. The docs already say to dedupe on (subscription.id, messageId), and messageId is the webhook-id. The docs do not say that webhook-id must equal eventId.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
  • I fully understand the code in this pull request, including any code generated with AI assistance.
  • Docs: I updated docs/ for this change, or this change is not user-facing.
  • Changeset: I added a changeset (pnpm changeset), or this PR does not change a published package.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Root cause

Issue. An app that uses createMCPEventWebhook drops every event from a server that sends a per-message webhook-id, as SEP-3415 requires. The receiver returns 400 at stage: 'envelope' with "Event does not match the subscription", and the server retries until it stops. gap, terminated and verification envelopes are not affected, because the receiver does not compare their webhook-id.

Cause. createMCPEventWebhook rejects an event when classified.event.eventId !== webhookId. #1816 added this check.

Fix. Remove the eventId part of the check. The signature still binds webhook-id to the body, because the HMAC covers webhook-id, the timestamp and the raw body. onEvent still gets the header as messageId.

SEP-3415 separates the two ids because one event can match two subscriptions on the same receiver. The event then arrives twice with the same eventId. With a per-message webhook-id, the documented dedupe key (subscription.id, messageId) keeps both deliveries.

Possible alternatives

  • An option to require the old form. For example requireWebhookIdEqualsEventId. SEP-3415 forbids that form, so the option adds API that no caller needs.
  • Dedupe in the receiver. Store each (subscription.id, webhook-id) and skip repeats. That is a new feature with a new store contract, and the docs already give dedupe to the app. It is out of scope for this fix.

Test plan

Commands run, on Node 24.22 and pnpm 11.9.0:

  1. pnpm test:pr: pass (8 affected projects), and scan-dangling-dts is clean.
  2. pnpm exec vitest run in packages/ai-mcp: 671 passed.
  3. pnpm exec playwright test tests/mcp-events.spec.ts in testing/e2e: 4 passed.
  4. The same tests with the webhook.ts from main: they fail, as below.

Before the fix (vitest run tests/events, with webhook.ts from main):

 × accepts webhook-id a per-message id (SEP-3415)
 × delivers one event to two subscriptions with different webhook-ids
 × an emitted event reaches onEvent and advances the stored cursor
 × delivers a signed event over the network to onEvent and stores the cursor
 × retries a 503 from a throwing onEvent and delivers on the next attempt
AssertionError: expected 400 to be 204 // Object.is equality
      Tests  5 failed | 153 passed (158)
  2 failed
    [chromium] › tests/mcp-events.spec.ts:19:3 › ... › subscribe → emit → received contains the event
    [chromium] › tests/mcp-events.spec.ts:104:3 › ... › unsubscribe stops deliveries
  2 passed

After the fix:

      Tests  671 passed (671)
  4 passed (10.8s)

Manual test:

  1. On main, copy tests/events/webhook.test.ts from this branch into packages/ai-mcp.
  2. Run pnpm exec vitest run tests/events/webhook.test.ts in packages/ai-mcp. The per-message test fails with expected 400 to be 204.
  3. On this branch, run the same command. All tests pass.

How this PR makes testing easy: the unit tests cover both forms, and the Playwright spec covers the per-message form. There is no new example app.

Risk / rollback

Low. The receiver now accepts more deliveries, but each delivery still needs a valid signature, a fresh timestamp, a known subscription key and a matching event name. To roll back, revert this PR.

Posted by an AI agent with human oversight.

Summary by CodeRabbit

  • Bug Fixes
    • Webhook event deliveries accept per-message IDs that differ from the event ID, while remaining compatible with older servers that use matching IDs.
    • Event callbacks provide the message ID separately from the event ID, including when the same event is delivered to multiple subscriptions.
    1. 🦋 Changeset detected

      Latest commit: a32ffe89fa1de358f5f5cfb05cc61df1b8e9e53c

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 1 package
      NameType
      @tanstack/ai-mcpPatch

      Not sure what this means? Click here to learn what changesets are.

      Click here if you're a maintainer who wants to add another changeset to this PR

    2. tanstack-source added labelsbug

    3. Explain Change →

      No actionable comments were generated in the recent review.

      Walkthrough

      The MCP webhook receiver accepts webhook-id values that differ from the event’s eventId. The event-server helper generates a separate ID for each subscription delivery. Tests verify that message IDs and event IDs are reported separately.

      Changes: Webhook message ID handling

      Layer / File(s)Summary
      Webhook ID acceptance
      packages/ai-mcp/src/events/webhook.ts, packages/ai-mcp/tests/events/webhook.test.ts, .changeset/mcp-events-webhook-id-per-message.md
      The receiver no longer requires webhook-id to match eventId; it still checks the event name. Tests cover matching and distinct IDs and confirm that onEvent receives the message ID separately. The changeset documents the compatibility behavior and deduplication guidance.
      Subscription delivery IDs
      packages/ai-mcp/tests/helpers/events-server.ts, packages/ai-mcp/tests/events/webhook.test.ts, testing/e2e/src/lib/mcp-events-session.ts, testing/e2e/src/routes/api.mcp-events-control.ts, testing/e2e/tests/mcp-events.spec.ts
      The event-server helper generates a msg_ ID for each subscription delivery and reuses it for retries. Tests cover one event delivered to two subscriptions with distinct message IDs. E2E session data and responses include message IDs, and the E2E test checks them separately from event IDs.

      Estimated code review effort: 2 (Simple) | ~10 minutes

      Change: Bug fix

      Suggested reviewers: carlosziegler

      Merge Risk: Minimal · up to a32ff

      The webhook receiver now accepts per-message webhook IDs that differ from the event ID, and it still accepts the older form where they match. The behavior change is narrow and covered by tests. No merge-blocking risk is evident.

      Pre-merge checks: Passed 4

      Check nameStatusExplanation
      Title checkPassedThe title names the main change: the receiver in @tanstack/ai-mcp no longer requires webhook-id to equal eventId, so MCP Events deliveries with per-message IDs are accepted. The title is specific, con…
      Description checkPassedThe description follows the template. It has the Changes section, the full checklist, and the Release Impact section, with the changeset item checked. It also gives a clear root cause, fix, test plan …
      Linked Issues checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck skipped because no linked issues were found for this pull request.
      Full details: Title check

      Explanation

      The title names the main change: the receiver in @tanstack/ai-mcp no longer requires webhook-id to equal eventId, so MCP Events deliveries with per-message IDs are accepted. The title is specific, concise, and matches the changeset, code change, and tests.

      Full details: Description check

      Explanation

      The description follows the template. It has the Changes section, the full checklist, and the Release Impact section, with the changeset item checked. It also gives a clear root cause, fix, test plan with results, and risk/rollback. The Changes section is detailed. The docs item is checked, and the description says no docs change was needed, which is a minor mismatch with the checkbox wording but is explained.

      Finishing Touches

      Generate unit tests (beta)

      • Create a new PR
      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      Share

      Recent review info

      Run configuration

      • Source mode: Auto
      • Repository: TanStack/ai
      • Branch: main
      • File: .coderabbit.yaml
      • Commit: 1888233
      • Layers: Repository YAML
      • Review profile: CHILL
      • Plan: Advanced
      • Run ID: 6bebec67-4cbb-418c-bb0b-552778c280b3
      Commits

      Reviewing files that changed from the base of the PR and between 0ea2ccd4cfb63be316806e8a84113cbd60e01a5c and a32ffe89fa1de358f5f5cfb05cc61df1b8e9e53c.

      Files selected for processing: 3

      • testing/e2e/src/lib/mcp-events-session.ts
      • testing/e2e/src/routes/api.mcp-events-control.ts
      • testing/e2e/tests/mcp-events.spec.ts

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

    4. Thanks for the PR, @leggetter! 🙌 @tombeckenham will take a look.

      Automated pre-review checks

      • ✅ CI passing
      • ✅ No merge conflicts
      • ✅ Changeset present
      • ⚠️ No E2E test changes detected — behavior changes need coverage under testing/e2e/ (see CONTRIBUTING)
      Automated triage — a human review follows.
    5. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer

    6. tanstack-sourceBotcommented

      This PR is useful. It lets createMCPEventWebhook accept a webhook-id that differs from eventId. Related work is #1816. This PR does not link an issue.

      TanStack Source bot, value agent

    7. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: author

    8. github-actions[bot](GitHub profile, opens in a new tab) removed labelswaiting-on: maintainer

Sign in to join this conversation.