fix(core): instrument MCP transports before start (#23978)

Fixes missing MCP spans when a transport delivers queued requests during
`server.connect()`.

The MCP SDK installs its callbacks before calling `transport.start()`,
so instrumentation must run at that boundary. The temporary interceptor
restores `start()` before invoking it, preserving its receiver, Promise
and synchronous errors. Transports without a patchable `start()` retain
the post-connect fallback.

Regression tests cover MCP v1 and v2 in ESM/CJS, including optional
Sentry-managed OpenTelemetry setup. A deployed Worker A/B reproduced the
missing spans without the fix; the modern protocol entry path was
unaffected. This does not change OpenTelemetry providers, exporters or
propagation.

Fixes #23977

---------

Co-authored-by: OpenAI Codex <codex@openai.com>

Author: betegon

dev-packages/node-integration-tests/suites/tracing/mcp-server-streamed/instrument.mjs

@@ -6,4 +6,14 @@ Sentry.init({
   release: '1.0',
   tracesSampleRate: 1.0,
   transport: loggingTransport,
+  enableOpenTelemetrySetup: process.env.ENABLE_OTEL === 'true',
+});
+
+let initializeSpansStarted = 0;
+Sentry.getClient()?.on('spanStart', span => {
+  const attributes = Sentry.spanToJSON(span).attributes;
+  if (attributes['sentry.op'] === 'mcp.server' && attributes['mcp.method.name'] === 'initialize') {
+    initializeSpansStarted += 1;
+    span.setAttribute('test.mcp.initialize_spans_started', initializeSpansStarted);
+  }
 });

dev-packages/node-integration-tests/suites/tracing/mcp-server-streamed/scenario-start-v2.mjs

@@ -0,0 +1,30 @@
+import { Client } from '@modelcontextprotocol/client';
+import { InMemoryTransport, McpServer } from '@modelcontextprotocol/server';
+import { wrapMcpServerWithSentry } from '@sentry/node';
+
+const server = wrapMcpServerWithSentry(new McpServer({ name: 'Echo', version: '1.0.0' }));
+
+async function run() {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'test-client', version: '1.0.0' }, { versionNegotiation: { mode: 'legacy' } });
+  const originalSend = clientTransport.send.bind(clientTransport);
+  const requestQueued = new Promise(resolve => {
+    clientTransport.send = async (...args) => {
+      const result = await originalSend(...args);
+      if (args[0]?.method === 'initialize') {
+        resolve();
+      }
+      return result;
+    };
+  });
+
+  const clientConnection = client.connect(clientTransport);
+  await requestQueued;
+  await server.connect(serverTransport);
+  await clientConnection;
+
+  await client.close();
+  await server.close();
+}
+
+run();

dev-packages/node-integration-tests/suites/tracing/mcp-server-streamed/scenario-v1.mjs

@@ -0,0 +1,31 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { wrapMcpServerWithSentry } from '@sentry/node';
+
+const server = wrapMcpServerWithSentry(new McpServer({ name: 'Echo', version: '1.0.0' }));
+
+async function run() {
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'test-client', version: '1.0.0' });
+  const originalSend = clientTransport.send.bind(clientTransport);
+  const requestQueued = new Promise(resolve => {
+    clientTransport.send = async (...args) => {
+      const result = await originalSend(...args);
+      if (args[0]?.method === 'initialize') {
+        resolve();
+      }
+      return result;
+    };
+  });
+
+  const clientConnection = client.connect(clientTransport);
+  await requestQueued;
+  await server.connect(serverTransport);
+  await clientConnection;
+
+  await client.close();
+  await server.close();
+}
+
+run();

dev-packages/node-integration-tests/suites/tracing/mcp-server-streamed/test.ts

@@ -6,6 +6,20 @@ function mcpSpans(container: SerializedStreamedSpanContainer): SerializedStreame
   return container.items.filter(item => item.attributes['sentry.op']?.value === 'mcp.server');
 }
 
+function assertInitializeSpan(container: SerializedStreamedSpanContainer): void {
+  const initializeSpans = mcpSpans(container).filter(
+    span => span.attributes['mcp.method.name']?.value === 'initialize',
+  );
+
+  expect(initializeSpans).toHaveLength(1);
+  const initializeSpan = initializeSpans[0]!;
+  expect(initializeSpan.name).toBe('initialize');
+  expect(initializeSpan.status).toBe('ok');
+  expect(initializeSpan.attributes['sentry.op']).toEqual({ type: 'string', value: 'mcp.server' });
+  expect(initializeSpan.attributes['sentry.origin']).toEqual({ type: 'string', value: 'auto.function.mcp_server' });
+  expect(initializeSpan.attributes['test.mcp.initialize_spans_started']).toEqual({ type: 'integer', value: 1 });
+}
+
 describe('MCP server spans (streamed)', () => {
   afterAll(() => {
     cleanupChildProcesses();
@@ -43,4 +57,31 @@ describe('MCP server spans (streamed)', () => {
         .completed();
     });
   });
+
+  createEsmAndCjsTests(__dirname, 'scenario-start-v2.mjs', 'instrument.mjs', (createTestRunner, test) => {
+    test('captures an MCP v2 initialize request queued before transport start once', async () => {
+      await createTestRunner().unordered().expect({ span: assertInitializeSpan }).start().completed();
+    });
+
+    test('captures the queued request with Sentry OpenTelemetry setup enabled', async () => {
+      await createTestRunner()
+        .withEnv({ ENABLE_OTEL: 'true' })
+        .unordered()
+        .expect({ span: assertInitializeSpan })
+        .start()
+        .completed();
+    });
+  });
+
+  createEsmAndCjsTests(
+    __dirname,
+    'scenario-v1.mjs',
+    'instrument.mjs',
+    (createTestRunner, test) => {
+      test('captures an MCP v1 initialize request queued before transport start once', async () => {
+        await createTestRunner().unordered().expect({ span: assertInitializeSpan }).start().completed();
+      });
+    },
+    { additionalDependencies: { '@modelcontextprotocol/sdk': '1.30.0' } },
+  );
 });

packages/core/src/integrations/mcp-server/index.ts

@@ -10,6 +10,79 @@ import { validateMcpServerInstance } from './validation';
  */
 const wrappedMcpServerInstances = new WeakSet();
 
+function instrumentTransport(transport: MCPTransport, options: McpServerWrapperOptions): void {
+  wrapTransportOnMessage(transport, options);
+  wrapTransportSend(transport, options);
+  wrapTransportOnClose(transport);
+  wrapTransportError(transport);
+}
+
+function interceptTransportStart(transport: MCPTransport, beforeStart: () => void): () => void {
+  let transportStart: MCPTransport['start'];
+  let originalDescriptor: PropertyDescriptor | undefined;
+
+  try {
+    transportStart = transport.start;
+    originalDescriptor = Object.getOwnPropertyDescriptor(transport, 'start');
+  } catch {
+    return () => undefined;
+  }
+
+  if (typeof transportStart !== 'function') {
+    return () => undefined;
+  }
+
+  const originalStart = transportStart;
+  let isInstalled = false;
+
+  const restoreStart = (): void => {
+    if (!isInstalled) {
+      return;
+    }
+
+    try {
+      const currentDescriptor = Object.getOwnPropertyDescriptor(transport, 'start');
+      if (currentDescriptor?.value !== interceptedStart) {
+        isInstalled = false;
+        return;
+      }
+
+      if (originalDescriptor) {
+        Object.defineProperty(transport, 'start', originalDescriptor);
+        isInstalled = false;
+      } else if (Reflect.deleteProperty(transport, 'start')) {
+        isInstalled = false;
+      }
+    } catch {}
+  };
+
+  function interceptedStart(this: MCPTransport): Promise<void> {
+    // Restoring first keeps recursive calls and user-observed method identity identical to the original transport.
+    restoreStart();
+    beforeStart();
+    return originalStart.call(this);
+  }
+
+  const replacementDescriptor: PropertyDescriptor =
+    originalDescriptor && 'value' in originalDescriptor
+      ? { ...originalDescriptor, value: interceptedStart }
+      : {
+          configurable: originalDescriptor?.configurable ?? true,
+          enumerable: originalDescriptor?.enumerable ?? false,
+          writable: true,
+          value: interceptedStart,
+        };
+
+  try {
+    Object.defineProperty(transport, 'start', replacementDescriptor);
+    isInstalled = true;
+  } catch {
+    // The post-connect fallback preserves the previous behavior for transports which cannot be patched.
+  }
+
+  return restoreStart;
+}
+
 /**
  * Wraps an MCP Server instance with Sentry instrumentation.
  *
@@ -63,18 +136,30 @@ export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S,
 
   fill(serverInstance, 'connect', originalConnect => {
     return async function (this: MCPServerInstance, transport: MCPTransport, ...restArgs: unknown[]) {
-      const result = await (originalConnect as (...args: unknown[]) => Promise<unknown>).call(
-        this,
-        transport,
-        ...restArgs,
-      );
-
-      wrapTransportOnMessage(transport, captureOptions);
-      wrapTransportSend(transport, captureOptions);
-      wrapTransportOnClose(transport);
-      wrapTransportError(transport);
-
-      return result;
+      let isTransportInstrumented = false;
+      const instrumentTransportOnce = (): void => {
+        if (isTransportInstrumented) {
+          return;
+        }
+
+        isTransportInstrumented = true;
+        instrumentTransport(transport, captureOptions);
+      };
+      const restoreStart = interceptTransportStart(transport, instrumentTransportOnce);
+
+      try {
+        const result = await (originalConnect as (...args: unknown[]) => Promise<unknown>).call(
+          this,
+          transport,
+          ...restArgs,
+        );
+
+        instrumentTransportOnce();
+
+        return result;
+      } finally {
+        restoreStart();
+      }
     };
   });
 

packages/core/src/integrations/mcp-server/types.ts

@@ -65,6 +65,9 @@ export interface JsonRpcNotification {
  * @description Abstraction for MCP communication transport layer
  */
 export interface MCPTransport {
+  /** Starts the transport lifecycle. */
+  start?: () => Promise<void>;
+
   /**
    * Message handler for incoming JSON-RPC messages
    * The first argument is a JSON RPC message