Skip to content

feat(core): Enrich MCP SDK spans instead of duplicating them - #26309

Open
sentry-junior[bot] wants to merge 14 commits into
developfrom
feat/mcp-sdk-otel-handoff
Open

sentry-junior[bot] wants to merge 14 commits into
developfrom
feat/mcp-sdk-otel-handoff

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Why: The next @modelcontextprotocol/server release starts its own OpenTelemetry span for every MCP request and notification (modelcontextprotocol/typescript-sdk#3115). When the Sentry tracer provider is registered, that span reaches Sentry, so every request gets two nested server spans with the same name. That happens by default in nextjs, sveltekit, deno and vercel-edge, and anywhere enableOpenTelemetrySetup: true is set. This change adds our attributes to the span the MCP SDK starts instead of starting a second one. Upstream's docs tell Sentry users to remove the McpServer integration instead, but that loses tool arguments and results, which upstream deliberately doesn't record.

Non-obvious decisions:

  • The hook goes through Protocol._instrumentation. That field is package-internal, but the integration already reads _registeredTools and similar. Without the field (v1, v2 ≤ 2.4, openTelemetry: false), nothing changes.
  • Whether to hand off is decided per message, from the span the SDK starts: we catch it on spanStart. If it is a Sentry span, we enrich it. If it isn't (a non-Sentry tracer provider, or none at all), we start our own span. We don't inspect the OpenTelemetry API registry.
  • Our fallback span starts when the SDK opens its scope, not when it runs the handler, because the SDK rejects some requests (method not found, invalid params) without running one. Messages the SDK drops before it opens a scope no longer get a span on servers whose SDK instrumentation doesn't reach Sentry.
  • The SDK ends its span before transport.send. Response attributes (tool/prompt results, initialize server info) are therefore applied from the SDK's end callback, not from send-time correlation.

How to review: Start with upstreamInstrumentation.ts, then the hand-off branches in transport.ts. The changes in spans.ts and correlation.ts only separate building attributes from starting or ending the span, so both paths can use them.

Unsure about:

  • With the hand-off, the MCP span is a child of the http.server span instead of its own segment, because forceTransaction can't be applied after the span is started. Is that fine for the MCP insights views?
  • The new optional e2e variant node-express-mcp-v2 (MCP SDK OpenTelemetry) installs the unreleased SDK from pkg.pr.new, pinned to typescript-sdk 919bb8e. The app's pnpm-workspace.yaml sets blockExoticSubdeps: false because the previews depend on each other by URL. Once upstream releases, the variant should switch to npm and that setting can go.

Refs #26078

via Francesco Gringl-Novy, @mydea.

--

View Session [Sentry]

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

size-limit report 📦

Compared: e99e87c (PR test merge using develop at 452f91e)

Against: 452f91e (develop) · base run #66586

✅ Baseline matches: this diff contains only this PR's changes.

Path Size % Change Change
@sentry/browser 30.18 kB - -
@sentry/browser - with treeshaking flags 28.37 kB - -
@sentry/browser - with treeshaking flags tracing without tracing 28.28 kB - -
@sentry/browser (incl. Tracing) 52.74 kB - -
@sentry/browser (incl. Tracing Core) 40.27 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 52.75 kB - -
@sentry/browser (incl. Tracing, Profiling) 55.63 kB - -
@sentry/browser (incl. Tracing, Replay) 92.79 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 81.61 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 97.16 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 110.39 kB - -
@sentry/browser (incl. Feedback) 47.8 kB - -
@sentry/browser (incl. sendFeedback) 30.76 kB - -
@sentry/browser (incl. FeedbackAsync) 35.76 kB - -
@sentry/browser (incl. Metrics) 31.5 kB - -
@sentry/browser (incl. Logs) 31.78 kB - -
@sentry/browser (incl. Metrics & Logs) 32.44 kB - -
@sentry/react 32.19 kB - -
@sentry/react (incl. Tracing) 55.39 kB - -
@sentry/vue 38.38 kB - -
@sentry/vue (incl. Tracing) 55.69 kB - -
@sentry/svelte 30.19 kB - -
@sentry/remix (Remix 3 client bundle) 58.4 kB - -
CDN Bundle 32.11 kB - -
CDN Bundle (incl. Tracing) 53.15 kB - -
CDN Bundle (incl. Logs, Metrics) 34.89 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 55.71 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 75.92 kB - -
CDN Bundle (incl. Tracing, Replay) 91.03 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 93.65 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 96.42 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 98.98 kB - -
CDN Bundle - uncompressed 93.8 kB - -
CDN Bundle (incl. Tracing) - uncompressed 157.13 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 102.13 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 164.75 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 232.25 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 277.28 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 284.91 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 289.07 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 296.69 kB - -
@sentry/nextjs (client) 59.02 kB - -
@sentry/sveltekit (client) 54.03 kB - -
@sentry/core/server 45.48 kB +0.98% +441 B 🔺
@sentry/core/browser 14.4 kB - -
@sentry/node 152.43 kB +0.28% +425 B 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 83.34 kB - -
@sentry/node - without tracing 88.67 kB -0.01% -4 B 🔽
@sentry/node - without channel injection 141.38 kB +0.32% +440 B 🔺
@sentry/aws-serverless 99.03 kB -0.01% -4 B 🔽
@sentry/cloudflare (withSentry) - minified 206.95 kB - -
@sentry/cloudflare (withSentry) 480.37 kB - -
@sentry/nextjs/cloudflare (withSentry) - minified 232.31 kB - -

View base workflow run

@github-actions

Copy link
Copy Markdown
Contributor

One or more gzipped bundles increased by more than 500 bytes. If this increase is intentional, add the Accept Bundlesize Increase label to this PR to rerun and accept the check.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Optional E2E tests

Some optional checks were not successful. They do not block the merge. 1 not successful, 63 successful. See the run.

Check Status
❌ CI: Optional E2E Tests / E2E nextjs-16-cacheComponents (cloudflare) Test (optional) Failing after 11m Details
Successful checks
Check Status
✅ CI: Optional E2E Tests / E2E astro-7 Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E astro-7-static Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E cloudflare-flue-send-to-sentry Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (turbo) Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E nextjs-orpc Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E supabase-nextjs Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E node-express-mcp-v2 Test (optional) Successful in 30s Details
✅ CI: Optional E2E Tests / E2E nestjs-12 (deno) Test (optional) Successful in 52s Details
✅ CI: Optional E2E Tests / E2E node-eve Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E debug-id-sourcemaps Test (optional) Successful in 46s Details
✅ CI: Optional E2E Tests / E2E node-express-send-to-sentry-static Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-eve (orchestrion) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E cloudflare-pi-durable Test (optional) Successful in 46s Details
✅ CI: Optional E2E Tests / E2E node-eve (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E deno (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps Test (optional) Successful in 36s Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps (static / nuxt generate) Test (optional) Successful in 34s Details
✅ CI: Optional E2E Tests / E2E cloudflare-workers-send-to-sentry Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E cloudflare-think (ai v6) Test (optional) Successful in 58s Details
✅ CI: Optional E2E Tests / E2E cloudflare-pi-durable (latest) Test (optional) Successful in 40s Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-pi-durable (latest) Test (optional) Successful in 40s Details
✅ CI: Optional E2E Tests / E2E nextjs-15 (latest) Test (optional) Successful in 3m Details
✅ CI: Optional E2E Tests / E2E cloudflare-think Test (optional) Successful in 57s Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (cloudflare, latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nuxt-5 Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nextjs-16-tunnel (cloudflare) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-fastify-6 Test (optional) Successful in 31s Details
✅ CI: Optional E2E Tests / E2E nestjs-12 (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nextjs-16 (vinext, bun) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5 (kv-cache) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nestjs-12 (bun) Test (optional) Successful in 51s Details
✅ CI: Optional E2E Tests / E2E cloudflare-mastra Test (optional) Successful in 45s Details
✅ CI: Optional E2E Tests / E2E node-mastra (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-eve (content off, latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries (latest) Test (optional) Successful in 48s Details
✅ CI: Optional E2E Tests / E2E node-mastra Test (optional) Successful in 59s Details
✅ CI: Optional E2E Tests / E2E cloudflare-agent Test (optional) Successful in 47s Details
✅ CI: Optional E2E Tests / E2E node-flue Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5-tunnel Test (optional) Successful in 38s Details
✅ CI: Optional E2E Tests / E2E node-express-mcp-v1 Test (optional) Successful in 34s Details
✅ CI: Optional E2E Tests / E2E node-flue (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-openai-decisions (latest) Test (optional) Successful in 26s Details
✅ CI: Optional E2E Tests / E2E react-send-to-sentry Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries Test (optional) Successful in 57s Details
✅ CI: Optional E2E Tests / E2E node-openai-decisions Test (optional) Successful in 32s Details
✅ CI: Optional E2E Tests / E2E cloudflare-workers-without-tracing-send-to-sentry Test (optional) Successful in 5m Details
✅ CI: Optional E2E Tests / E2E nextjs-14 (latest) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E gen-ai-libraries (cloudflare) Test (optional) Successful in 44s Details
✅ CI: Optional E2E Tests / E2E nestjs-12 (cloudflare) Test (optional) Successful in 40s Details
✅ CI: Optional E2E Tests / E2E nuxt-5-cloudflare Test (optional) Successful in 38s Details
✅ CI: Optional E2E Tests / E2E node-express-send-to-sentry Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E node-pi-durable Test (optional) Successful in 36s Details
✅ CI: Optional E2E Tests / E2E node-express-mcp-v2 (MCP SDK OpenTelemetry) Test (optional) Successful in 29s Details
✅ CI: Optional E2E Tests / E2E react-router-7-framework-instrumentation Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E nuxt-5 (development) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E solidstart-2 Test (optional) Successful in 53s Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react (latest) Test (optional) Successful in 2m Details
✅ CI: Optional E2E Tests / E2E vue-3 (no Options API) Test (optional) Successful in 1m Details
✅ CI: Optional E2E Tests / E2E nuxt-5-sourcemaps (client source maps kept) Test (optional) Successful in 43s Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react-sourcemaps Test (optional) Successful in 35s Details
✅ CI: Optional E2E Tests / E2E solidstart-2-tunnel Test (optional) Successful in 52s Details
✅ CI: Optional E2E Tests / E2E tanstackstart-react-cloudflare Test (optional) Successful in 44s Details

@mydea mydea self-assigned this Nov 12, 2026
sentry-junior Bot and others added 8 commits November 16, 2026 08:09
@modelcontextprotocol/server starts its own OpenTelemetry span for every MCP
request and notification once a tracer provider is registered. With the
Sentry tracer provider (e.g. @sentry/nextjs, @sentry/sveltekit, @sentry/deno,
or enableOpenTelemetrySetup: true) every request ended up with two server
spans. The MCP server instrumentation now adds its attributes to the span the
MCP SDK starts and only starts its own span when the SDK records nothing.

Refs #26078

Co-Authored-By: Francesco Gringl-Novy <francesco.novy@sentry.io>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Co-Authored-By: Francesco Gringl-Novy <francesco.novy@sentry.io>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
…n config

Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Moves the pnpm exotic-subdeps setting into the e2e app's pnpm-workspace.yaml.

Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
@sentry-junior
sentry-junior Bot force-pushed the feat/mcp-sdk-otel-handoff branch from c63a8ef to b4160a2 Compare November 16, 2026 08:10
sentry-junior Bot and others added 2 commits November 16, 2026 08:16
…e OpenTelemetry global

Whether the MCP SDK's span reaches Sentry is now decided from the span it starts, so the hand-off no longer
reads the private OpenTelemetry API registry. When it does not reach Sentry, our own span starts as soon as the
SDK opens its scope, so requests the SDK rejects without running a handler still get a span.
Co-Authored-By: Francesco Gringl-Novy <2411343+mydea@users.noreply.github.com>
@mydea
mydea marked this pull request as ready for review November 16, 2026 08:44
@mydea
mydea requested review from a team and JPeer264 November 16, 2026 08:44
@sentry-junior
sentry-junior Bot requested a review from mydea November 16, 2026 08:44

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

The MCP SDK activates its span through the OpenTelemetry context, which does not reach Sentry's scope on
runtimes without an OpenTelemetry context manager (e.g. Deno), so handler spans and errors were not nested.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit dbcbed0. Configure here.

Without an OpenTelemetry context manager (e.g. Deno), the SDK's span was not active in transport.send, so
outgoing notifications still got a second span.

@isaacs isaacs left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the hand-off, the MCP span is a child of http.server (or of the remote parent from _meta) and not its own segment. Without the hand-off, it is still a forced transaction. So span shape depends on whether a tracer provider is registered, and the same app can change shape after an SDK upgrade. Under span streaming (the default), the MCP insights views query spans by op, so I expect them to still work. I did not verify the product side. The static (transaction) lifecycle is the riskier case, because MCP data then lives inside the http.server transaction.

Suggestion: get a yes from the team that owns the MCP insights views before landing, and say in the CHANGELOG or PR body that MCP spans are no longer segments when the MCP SDK's OTel spans reach Sentry. The PR can't fix this, because forceTransaction can't apply after the SDK starts the span.

The design is sound and as small as it can be.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants