feat(core): capture MCP OAuth client names per request

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

@@ -0,0 +1,8 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  tracesSampleRate: 1,
+  transport: loggingTransport,
+});

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

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { startSpan, wrapMcpServerWithSentry } from '@sentry/node';
+
+const requestContext = new AsyncLocalStorage();
+let resolverCalls = 0;
+const server = wrapMcpServerWithSentry(new McpServer({ name: 'test-server', version: '1.0.0' }), {
+  getOAuthClientName(authInfo) {
+    resolverCalls++;
+    return authInfo?.extra?.clientName ?? requestContext.getStore();
+  },
+});
+server.registerTool('echo', {}, async () => ({ content: [{ type: 'text', text: 'ok' }] }));
+const transport = new WebStandardStreamableHTTPServerTransport({
+  sessionIdGenerator: () => 'test-session',
+  enableJsonResponse: true,
+});
+
+async function request(id, method, clientName, contextName) {
+  const params =
+    method === 'initialize'
+      ? { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'protocol-v1', version: '1.0.0' } }
+      : {};
+  const response = await requestContext.run(contextName, async () => {
+    await new Promise(resolve => setImmediate(resolve));
+    return transport.handleRequest(
+      new Request('https://example.test/mcp', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'MCP-Protocol-Version': '2025-11-25',
+          ...(method !== 'initialize' && { 'Mcp-Session-Id': 'test-session' }),
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      }),
+      {
+        authInfo: clientName
+          ? { clientId: id, token: 'test-token', scopes: ['test-scope'], extra: { clientName } }
+          : undefined,
+      },
+    );
+  });
+  if (id === undefined) {
+    assert.equal(response.status, 202);
+    return;
+  }
+  assert.equal(response.status, 200);
+  const body = await response.json();
+  assert.equal(body.id, id);
+  if (method === 'resources/list') {
+    assert.equal(body.error.code, -32601);
+  } else {
+    assert.equal(body.error, undefined);
+    if (method === 'tools/list') {
+      assert.equal(body.result.tools[0].name, 'echo');
+    } else {
+      assert.equal(body.result.protocolVersion, '2025-11-25');
+    }
+  }
+}
+
+startSpan({ name: 'oauth requests' }, async span => {
+  await server.connect(transport);
+  await request('discovery', 'initialize', 'Registered Discovery');
+  await request(undefined, 'notifications/initialized', 'Notification Client');
+  await Promise.all([
+    request('context', 'tools/list', undefined, 'Registered Context'),
+    request('unsupported', 'resources/list', 'Registered Unsupported'),
+    request('missing', 'tools/list'),
+  ]);
+  assert.equal(resolverCalls, 4);
+  await server.close();
+  span.setAttribute('test.responses.checked', true);
+});

dev-packages/node-integration-tests/suites/tracing/mcp-server-oauth-client/scenario-v2.mjs

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { startSpan, wrapMcpServerWithSentry } from '@sentry/node';
+
+const requestContext = new AsyncLocalStorage();
+let resolverCalls = 0;
+const handler = createMcpHandler(async () => {
+  await new Promise(resolve => setImmediate(resolve));
+  const server = wrapMcpServerWithSentry(new McpServer({ name: 'test-server', version: '1.0.0' }), {
+    getOAuthClientName(authInfo) {
+      resolverCalls++;
+      return authInfo?.extra?.clientName ?? requestContext.getStore();
+    },
+  });
+  server.registerTool('echo', {}, async () => ({ content: [{ type: 'text', text: 'ok' }] }));
+  return server;
+});
+
+async function request(id, method, clientName, contextName) {
+  const params = {
+    _meta: {
+      'io.modelcontextprotocol/protocolVersion': '2026-07-28',
+      'io.modelcontextprotocol/clientCapabilities': {},
+      ...(id !== 'missing' && {
+        'io.modelcontextprotocol/clientInfo': { name: `protocol-${id}`, version: '1.0.0' },
+      }),
+    },
+  };
+  const response = await requestContext.run(contextName, () =>
+    handler.fetch(
+      new Request('https://example.test/mcp', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          'MCP-Protocol-Version': '2026-07-28',
+          'MCP-Method': method,
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+      }),
+      {
+        authInfo: clientName
+          ? { clientId: id, token: 'test-token', scopes: ['test-scope'], extra: { clientName } }
+          : undefined,
+      },
+    ),
+  );
+  const body = await response.json();
+  assert.equal(body.id, id);
+  if (method === 'resources/list') {
+    assert.equal(response.status, 404);
+    assert.equal(body.error.code, -32601);
+  } else {
+    assert.equal(response.status, 200);
+    assert.equal(body.error, undefined);
+    if (method === 'tools/list') {
+      assert.equal(body.result.tools[0].name, 'echo');
+    } else {
+      assert.ok(body.result.supportedVersions.includes('2026-07-28'));
+    }
+  }
+}
+
+startSpan({ name: 'oauth requests' }, async span => {
+  await Promise.all([
+    request('discovery', 'server/discover', 'Registered Discovery'),
+    request('context', 'tools/list', undefined, 'Registered Context'),
+    request('unsupported', 'resources/list', 'Registered Unsupported'),
+    request('missing', 'tools/list'),
+  ]);
+  assert.equal(resolverCalls, 4);
+  await handler.close();
+  span.setAttribute('test.responses.checked', true);
+});

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

@@ -0,0 +1,79 @@
+import {
+  MCP_AUTH_CLIENT_NAME,
+  MCP_CLIENT_NAME,
+  MCP_METHOD_NAME,
+  MCP_REQUEST_ID,
+  SENTRY_OP,
+} from '@sentry/conventions/attributes';
+import { MCP_SERVER } from '@sentry/conventions/op';
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('MCP OAuth client attribution', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  for (const { version, expectedRequests, additionalDependencies } of [
+    {
+      version: 'v1',
+      expectedRequests: [
+        ['discovery', 'initialize', 'Registered Discovery', 'protocol-v1'],
+        ['context', 'tools/list', 'Registered Context', 'protocol-v1'],
+        ['unsupported', 'resources/list', 'Registered Unsupported', 'protocol-v1'],
+        ['missing', 'tools/list', undefined, 'protocol-v1'],
+      ],
+      additionalDependencies: { '@modelcontextprotocol/sdk': '1.30.0' },
+    },
+    {
+      version: 'v2',
+      expectedRequests: [
+        ['discovery', 'server/discover', 'Registered Discovery', 'protocol-discovery'],
+        ['context', 'tools/list', 'Registered Context', 'protocol-context'],
+        ['unsupported', 'resources/list', 'Registered Unsupported', 'protocol-unsupported'],
+        ['missing', 'tools/list', undefined, undefined],
+      ],
+    },
+  ]) {
+    createEsmAndCjsTests(
+      __dirname,
+      `scenario-${version}.mjs`,
+      'instrument.mjs',
+      (createTestRunner, test) => {
+        test(`keeps ${version} OAuth identity request-local and separate from MCP identity`, async () => {
+          const runner = createTestRunner();
+          const spansPromise = runner.collectStreamedSpans(
+            spans =>
+              spans.some(span => span.is_segment && span.name === 'oauth requests') &&
+              expectedRequests.every(([id]) =>
+                spans.some(
+                  span =>
+                    span.attributes[SENTRY_OP]?.value === MCP_SERVER && span.attributes[MCP_REQUEST_ID]?.value === id,
+                ),
+              ),
+          );
+
+          await runner.start().completed();
+
+          const spans = await spansPromise;
+          const root = spans.find(span => span.is_segment && span.name === 'oauth requests');
+          expect(root?.attributes['test.responses.checked']?.value).toBe(true);
+          const requests = spans.filter(
+            span => span.attributes[SENTRY_OP]?.value === MCP_SERVER && span.attributes[MCP_REQUEST_ID],
+          );
+          expect(requests).toHaveLength(expectedRequests.length);
+          expect(
+            requests.map(({ attributes }) => [
+              attributes[MCP_REQUEST_ID]?.value,
+              attributes[MCP_METHOD_NAME]?.value,
+              attributes[MCP_AUTH_CLIENT_NAME]?.value,
+              attributes[MCP_CLIENT_NAME]?.value,
+            ]),
+          ).toEqual(expect.arrayContaining(expectedRequests));
+          expect(JSON.stringify(spans)).not.toContain('Notification Client');
+        });
+      },
+      { additionalDependencies },
+    );
+  }
+});

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

@@ -5,7 +5,7 @@ import type { MCPServerInstance, McpServerWrapperOptions, MCPTransport } from '.
 import { validateMcpServerInstance } from './validation';
 
 /**
- * Maps each wrapped MCP server instance to the mutable capture options that the transport
+ * Maps each wrapped MCP server instance to the mutable instrumentation options that the transport
  * instrumentation reads (per message). Prevents double-wrapping while still letting a later
  * `wrapMcpServerWithSentry` fill in options left unset by an earlier wrap — e.g. an auto-wrap at
  * construction installs no explicit options, so a manual override still applies.
@@ -14,8 +14,8 @@ import { validateMcpServerInstance } from './validation';
 const wrappedMcpServerOptions = new WeakMap<object, McpServerWrapperOptions>();
 
 /**
- * Fill in capture options not explicitly set by an earlier wrap. Only unset fields are written, so
- * the first explicit `recordInputs`/`recordOutputs` wins, but an auto-wrap that set neither still
+ * Fill in options not explicitly set by an earlier wrap. Only unset fields are written, so
+ * the first explicit value wins, but an auto-wrap that set no options still
  * yields to a later manual override. Mutating the stored object updates the live transport
  * instrumentation, which reads it per message.
  */
@@ -29,6 +29,9 @@ function applyMissingMcpOptions(target: McpServerWrapperOptions, source: McpServ
   if (target.recordOutputs === undefined && source.recordOutputs !== undefined) {
     target.recordOutputs = source.recordOutputs;
   }
+  if (target.getOAuthClientName === undefined && source.getOAuthClientName !== undefined) {
+    target.getOAuthClientName = source.getOAuthClientName;
+  }
 }
 
 function instrumentTransport(transport: MCPTransport, options: McpServerWrapperOptions): void {
@@ -117,8 +120,8 @@ function interceptTransportStart(transport: MCPTransport, beforeStart: () => voi
  * convention (consistent with other SDK integrations), but is not required.
  *
  * Calling this more than once on the same instance never patches it twice. Options behave like a
- * snapshot from the first *explicit* wrap: the first `recordInputs`/`recordOutputs` value set for a
- * field wins, but a field left unset can still be filled by a later call. So when the SDK auto-wraps
+ * snapshot from the first *explicit* wrap: the first value set for each option wins,
+ * but a field left unset can still be filled by a later call. So when the SDK auto-wraps
  * the server at construction (via the `mcpServer` integration) with no explicit options, a later
  * manual `wrapMcpServerWithSentry(server, { recordInputs, recordOutputs })` still applies.
  *
@@ -145,8 +148,19 @@ function interceptTransportStart(transport: MCPTransport, beforeStart: () => voi
  * await server.connect(transport);
  * ```
  *
+ * @example
+ * ```typescript
+ * // Read application-defined metadata supplied by the authentication middleware.
+ * const server = Sentry.wrapMcpServerWithSentry(mcpServer, {
+ *   getOAuthClientName: authInfo => {
+ *     const name = authInfo?.extra?.clientName;
+ *     return typeof name === 'string' ? name : undefined;
+ *   },
+ * });
+ * ```
+ *
  * @param mcpServerInstance - MCP server instance to instrument
- * @param options - Optional configuration for recording inputs and outputs
+ * @param options - Optional capture and OAuth client attribution configuration
  * @returns Instrumented server instance (same reference)
  */
 export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S, options?: McpServerWrapperOptions): S {
@@ -161,8 +175,8 @@ export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S,
   }
 
   const serverInstance = mcpServerInstance as MCPServerInstance;
-  const captureOptions: McpServerWrapperOptions = { ...options };
-  wrappedMcpServerOptions.set(mcpServerInstance, captureOptions);
+  const wrapperOptions: McpServerWrapperOptions = { ...options };
+  wrappedMcpServerOptions.set(mcpServerInstance, wrapperOptions);
 
   fill(serverInstance, 'connect', originalConnect => {
     return async function (this: MCPServerInstance, transport: MCPTransport, ...restArgs: unknown[]) {
@@ -173,7 +187,7 @@ export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S,
         }
 
         isTransportInstrumented = true;
-        instrumentTransport(transport, captureOptions);
+        instrumentTransport(transport, wrapperOptions);
       };
       const restoreStart = interceptTransportStart(transport, instrumentTransportOnce);
 

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

@@ -5,7 +5,7 @@
  * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
  */
 
-import { MCP_PROTOCOL_VERSION } from '@sentry/conventions/attributes';
+import { MCP_AUTH_CLIENT_NAME, MCP_PROTOCOL_VERSION } from '@sentry/conventions/attributes';
 import { getClient, getIsolationScope, withIsolationScope } from '../../currentScopes';
 import { withActiveSpan } from '../../tracing';
 import { startInactiveSpan } from '../../tracing/trace';
@@ -39,12 +39,29 @@ function resolveMcpOptions(options: McpServerWrapperOptions): ResolvedMcpOptions
   };
 }
 
+/** Resolves only the OAuth client name; optional telemetry must not interrupt MCP dispatch. */
+function resolveOAuthClientName(options: McpServerWrapperOptions, extra?: ExtraHandlerData): string | undefined {
+  if (!options.getOAuthClientName) {
+    return undefined;
+  }
+
+  try {
+    const authInfo = extra?.authInfo;
+    const name = options.getOAuthClientName(
+      authInfo ? { clientId: authInfo.clientId, extra: authInfo.extra } : undefined,
+    );
+    return typeof name === 'string' && name ? name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Wraps transport.onmessage to create spans for incoming messages.
  * Stores client info and protocol version only for legacy initialize requests.
  * Modern request metadata is read directly when building each message's span.
  * @param transport - MCP transport instance to wrap
- * @param options - MCP capture overrides
+ * @param options - MCP instrumentation options
  */
 export function wrapTransportOnMessage(transport: MCPTransport, options: McpServerWrapperOptions): void {
   if (transport.onmessage) {
@@ -71,6 +88,10 @@ export function wrapTransportOnMessage(transport: MCPTransport, options: McpServ
 
           return withIsolationScope(isolationScope, () => {
             const spanConfig = buildMcpServerSpanConfig(request, transport, extra as ExtraHandlerData, resolvedOptions);
+            const oauthClientName = resolveOAuthClientName(options, extra as ExtraHandlerData);
+            if (oauthClientName) {
+              spanConfig.attributes[MCP_AUTH_CLIENT_NAME] = oauthClientName;
+            }
             const span = startInactiveSpan(spanConfig);
 
             if (request.method === 'initialize' && messageSessionData) {