fix(mcp): retroactively wrap handlers registered before wrapMcpServerWithSentry (#20699)

`wrapMcpServerWithSentry` works by patching the registration methods
(`registerTool`, `registerResource`, `registerPrompt`) so that any
handler passed to them gets wrapped with Sentry error capture. The
problem: if tools are registered *before* wrapping, those already-stored
handlers are never touched, so errors from them are silently dropped.

This fix adds a retroactive pass (`wrapExistingHandlers`) that runs
immediately after the registration methods are patched. It walks the
McpServer's internal registries (`_registeredTools`,
`_registeredResources`, `_registeredResourceTemplates`,
`_registeredPrompts`) and wraps the stored callables in-place —
`executor` for tools, `readCallback` for resources and templates,
`handler` for prompts. These are the properties the MCP SDK reads at
call time (not captured by closure at registration), so replacing them
is equivalent to having wrapped the original call.

Both orderings are now fully supported. Wrapping at construction is
still recommended for consistency with how other SDK integrations work,
but it's not required.

**Recommended (wrap at construction):**
```ts
const server = Sentry.wrapMcpServerWithSentry(
  new McpServer({ name: 'my-server', version: '1.0.0' }),
);

server.registerTool('my-tool', schema, handler);
```

**Also works (wrap after registration):**
```ts
const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.registerTool('my-tool', schema, handler);

Sentry.wrapMcpServerWithSentry(server); // retroactively wraps the already-registered tool
```

The retroactive wrapping intentionally accesses private MCP SDK
internals. The JSDoc on `wrapExistingHandlers` includes a pinned
upstream source link and a note to re-verify the internal shapes when
upgrading the MCP SDK — all access is defensive and skips silently if a
property isn't found.

## Checklist

- [x] Tests added (`Retroactive handler wrapping` describe block in
`mcpServerWrapper.test.ts`)
- [x] No lint changes needed (pure TS, no new deps)
- [ ] Link an issue if there is one related to your pull request. If no
issue is linked, one will be auto-generated and linked.

Closes #issue_link_here

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: betegon

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

@@ -167,3 +167,74 @@ export function wrapAllMCPHandlers(serverInstance: MCPServerInstance): void {
   wrapResourceHandlers(serverInstance);
   wrapPromptHandlers(serverInstance);
 }
+
+/**
+ * Retroactively wraps handlers on tools, resources, and prompts that were registered
+ * before `wrapMcpServerWithSentry` was called.
+ *
+ * The MCP SDK stores registered entries in private maps and invokes them via the entry's
+ * own property at call time — `executor` for tools, `readCallback` for resources, and
+ * `handler` for prompts. Replacing those properties
+ * in-place is therefore equivalent to having wrapped the original registration call.
+ *
+ * NOTE: This intentionally accesses private MCP SDK internals (`_registeredTools` etc.).
+ * The properties and their shapes are verified against @modelcontextprotocol/sdk source:
+ * https://github.com/modelcontextprotocol/typescript-sdk/blob/2c0c481cb9dbfd15c8613f765c940a5f5bace94d/packages/server/src/server/mcp.ts#L304
+ * When upgrading the MCP SDK, re-verify that these internal maps and their callable
+ * properties still exist and are invoked directly (not captured by closure at registration).
+ * All access is defensive — if a property is absent or not a function we skip silently.
+ * @internal
+ */
+export function wrapExistingHandlers(serverInstance: MCPServerInstance): void {
+  const server = serverInstance as unknown as Record<string, unknown>;
+
+  // Tools: MCP SDK calls registeredTool.executor (generated from handler at registration time)
+  const registeredTools = server['_registeredTools'];
+  if (registeredTools && typeof registeredTools === 'object') {
+    for (const [name, tool] of Object.entries(registeredTools as Record<string, Record<string, unknown>>)) {
+      if (typeof tool['executor'] === 'function') {
+        tool['executor'] = createWrappedHandler(tool['executor'] as MCPHandler, 'registerTool', name);
+      }
+    }
+  }
+
+  // Resources: MCP SDK calls registeredResource.readCallback
+  const registeredResources = server['_registeredResources'];
+  if (registeredResources && typeof registeredResources === 'object') {
+    for (const [name, resource] of Object.entries(registeredResources as Record<string, Record<string, unknown>>)) {
+      if (typeof resource['readCallback'] === 'function') {
+        resource['readCallback'] = createWrappedHandler(
+          resource['readCallback'] as MCPHandler,
+          'registerResource',
+          name,
+        );
+      }
+    }
+  }
+
+  // Resource templates: MCP SDK calls registeredResourceTemplate.readCallback
+  const registeredResourceTemplates = server['_registeredResourceTemplates'];
+  if (registeredResourceTemplates && typeof registeredResourceTemplates === 'object') {
+    for (const [name, template] of Object.entries(
+      registeredResourceTemplates as Record<string, Record<string, unknown>>,
+    )) {
+      if (typeof template['readCallback'] === 'function') {
+        template['readCallback'] = createWrappedHandler(
+          template['readCallback'] as MCPHandler,
+          'registerResource',
+          name,
+        );
+      }
+    }
+  }
+
+  // Prompts: MCP SDK calls registeredPrompt.handler
+  const registeredPrompts = server['_registeredPrompts'];
+  if (registeredPrompts && typeof registeredPrompts === 'object') {
+    for (const [name, prompt] of Object.entries(registeredPrompts as Record<string, Record<string, unknown>>)) {
+      if (typeof prompt['handler'] === 'function') {
+        prompt['handler'] = createWrappedHandler(prompt['handler'] as MCPHandler, 'registerPrompt', name);
+      }
+    }
+  }
+}

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

@@ -1,6 +1,6 @@
 import { getClient } from '../../currentScopes';
 import { fill } from '../../utils/object';
-import { wrapAllMCPHandlers } from './handlers';
+import { wrapAllMCPHandlers, wrapExistingHandlers } from './handlers';
 import { wrapTransportError, wrapTransportOnClose, wrapTransportOnMessage, wrapTransportSend } from './transport';
 import type { MCPServerInstance, McpServerWrapperOptions, MCPTransport, ResolvedMcpOptions } from './types';
 import { validateMcpServerInstance } from './validation';
@@ -18,17 +18,24 @@ const wrappedMcpServerInstances = new WeakSet();
  * and versions that expose the newer `registerTool`/`registerResource`/`registerPrompt` API (introduced in 1.x, sole API in 2.x).
  * Automatically instruments transport methods and handler functions for comprehensive monitoring.
  *
+ * Both call orderings are supported: wrapping before or after registering tools, resources,
+ * and prompts. Sentry patches the registration methods for future handlers and retroactively
+ * wraps any already-registered ones. Wrapping at construction time is recommended by
+ * convention (consistent with other SDK integrations), but is not required.
+ *
  * @example
  * ```typescript
  * import * as Sentry from '@sentry/core';
  * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
  *
- * // Default: inputs/outputs captured based on sendDefaultPii option
+ * // Wrap first, then register tools — this is the correct order
  * const server = Sentry.wrapMcpServerWithSentry(
  *   new McpServer({ name: "my-server", version: "1.0.0" })
  * );
  *
+ * server.registerTool('my-tool', schema, handler);
+ *
  * // Explicitly control input/output capture
  * const server = Sentry.wrapMcpServerWithSentry(
  *   new McpServer({ name: "my-server", version: "1.0.0" }),
@@ -80,6 +87,8 @@ export function wrapMcpServerWithSentry<S extends object>(mcpServerInstance: S,
 
   wrapAllMCPHandlers(serverInstance);
 
+  wrapExistingHandlers(serverInstance);
+
   wrappedMcpServerInstances.add(mcpServerInstance);
   return mcpServerInstance;
 }

packages/core/test/lib/integrations/mcp-server/mcpServerWrapper.test.ts

@@ -2,7 +2,11 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as currentScopes from '../../../../src/currentScopes';
 import { wrapMcpServerWithSentry } from '../../../../src/integrations/mcp-server';
 import * as tracingModule from '../../../../src/tracing';
-import { createMockMcpServer, createMockMcpServerWithRegisterApi } from './testUtils';
+import {
+  createMockMcpServer,
+  createMockMcpServerWithPreregisteredHandlers,
+  createMockMcpServerWithRegisterApi,
+} from './testUtils';
 
 describe('wrapMcpServerWithSentry', () => {
   const startSpanSpy = vi.spyOn(tracingModule, 'startSpan');
@@ -145,6 +149,41 @@ describe('wrapMcpServerWithSentry', () => {
     });
   });
 
+  describe('Retroactive handler wrapping (handlers registered before wrapMcpServerWithSentry)', () => {
+    it('should replace executor/readCallback/handler on pre-registered entries with wrapped versions', () => {
+      const server = createMockMcpServerWithPreregisteredHandlers();
+      const { toolExecutor, resourceReadCallback, resourceTemplateReadCallback, promptHandler } = server._originals;
+
+      wrapMcpServerWithSentry(server);
+
+      expect(server._registeredTools['my-tool']!.executor).not.toBe(toolExecutor);
+      expect(server._registeredResources['res://my-resource']!.readCallback).not.toBe(resourceReadCallback);
+      expect(server._registeredResourceTemplates['my-template']!.readCallback).not.toBe(resourceTemplateReadCallback);
+      expect(server._registeredPrompts['my-prompt']!.handler).not.toBe(promptHandler);
+    });
+
+    it('should still wrap the registration methods for future handlers', () => {
+      const server = createMockMcpServerWithPreregisteredHandlers();
+      const originalRegisterTool = server.registerTool;
+
+      wrapMcpServerWithSentry(server);
+
+      expect(server.registerTool).not.toBe(originalRegisterTool);
+    });
+
+    it('should not double-wrap if called twice on the same instance with pre-registered handlers', () => {
+      const server = createMockMcpServerWithPreregisteredHandlers();
+
+      wrapMcpServerWithSentry(server);
+      const executorAfterFirstWrap = server._registeredTools['my-tool']!.executor;
+
+      wrapMcpServerWithSentry(server);
+      const executorAfterSecondWrap = server._registeredTools['my-tool']!.executor;
+
+      expect(executorAfterFirstWrap).toBe(executorAfterSecondWrap);
+    });
+  });
+
   describe('Handler Wrapping (register* API)', () => {
     let mockServer: ReturnType<typeof createMockMcpServerWithRegisterApi>;
     let wrappedServer: ReturnType<typeof createMockMcpServerWithRegisterApi>;

packages/core/test/lib/integrations/mcp-server/testUtils.ts

@@ -15,6 +15,41 @@ export function createMockMcpServer() {
   };
 }
 
+/**
+ * Create a mock MCP server that simulates already having tools/resources/prompts registered
+ * (i.e. wrapMcpServerWithSentry is called after registration). Mirrors the internal shape
+ * used by McpServer v2: tools have an `executor`, resources/prompts have `readCallback`/`handler`.
+ */
+export function createMockMcpServerWithPreregisteredHandlers() {
+  const toolExecutor = vi.fn().mockResolvedValue({ content: [] });
+  const resourceReadCallback = vi.fn().mockResolvedValue({ contents: [] });
+  const resourceTemplateReadCallback = vi.fn().mockResolvedValue({ contents: [] });
+  const promptHandler = vi.fn().mockResolvedValue({ messages: [] });
+
+  return {
+    registerTool: vi.fn(),
+    registerResource: vi.fn(),
+    registerPrompt: vi.fn(),
+    connect: vi.fn().mockResolvedValue(undefined),
+    server: { setRequestHandler: vi.fn() },
+    // Simulated internal registries (mirrors McpServer v2 private fields)
+    _registeredTools: {
+      'my-tool': { executor: toolExecutor },
+    },
+    _registeredResources: {
+      'res://my-resource': { readCallback: resourceReadCallback },
+    },
+    _registeredResourceTemplates: {
+      'my-template': { readCallback: resourceTemplateReadCallback },
+    },
+    _registeredPrompts: {
+      'my-prompt': { handler: promptHandler },
+    },
+    // Expose the original fns so tests can assert wrapping happened
+    _originals: { toolExecutor, resourceReadCallback, resourceTemplateReadCallback, promptHandler },
+  };
+}
+
 /**
  * Create a mock MCP server instance using the new register* API (SDK >=1.x / 2.x)
  */